### Backend Development Setup and Run

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/development.md

Set up a virtual environment, activate it, install dependencies, and run the FastAPI application with hot-reloading.

```bash
cd backend
uv venv .venv
source .venv/bin/activate
uv sync
uvicorn src.main_refactored:app --reload --host 0.0.0.0 --port 8000
```

--------------------------------

### Install Waitlist Dependencies and Start Dev Server

Source: https://github.com/fujiwarachoki/supoclip/blob/main/CLAUDE.md

Installs dependencies using Bun and starts the development server for the waitlist application.

```bash
cd waitlist
bun install
bun run dev
```

--------------------------------

### Run SupoClip Frontend Locally

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/setup.md

Install frontend dependencies using npm and start the Next.js development server. This is for frontend-specific development without Docker.

```bash
cd frontend
npm install
npm run dev
```

--------------------------------

### Install New Dependencies

Source: https://github.com/fujiwarachoki/supoclip/blob/main/backend/REFACTORING_GUIDE.md

Install new dependencies like arq and redis. Use 'uv sync' for a quick install or 'uv pip install' for specific versions.

```bash
cd backend

# Install arq and redis
uv sync

# Or manually:
uv pip install arq>=0.26.0 redis>=5.0.0
```

--------------------------------

### Start Full Stack with Docker

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/development.md

Use these commands to build and run the entire SupoClip application using Docker Compose. Ensure Docker is installed and running.

```bash
docker-compose up -d --build
```

```bash
docker-compose logs -f
```

```bash
docker-compose down
```

--------------------------------

### Build and Start Next.js Production Server

Source: https://github.com/fujiwarachoki/supoclip/blob/main/AGENTS.md

Creates a production build of the Next.js application and then starts the production server. Run this from the frontend or waitlist directory.

```bash
cd frontend && npm run build && npm run start
```

--------------------------------

### Run SupoClip with Docker

Source: https://github.com/fujiwarachoki/supoclip/blob/main/QUICKSTART.md

Execute this script to build Docker images, start all services, and access the application. Ensure Docker Desktop is installed and running.

```bash
./start.sh
```

--------------------------------

### Install ffmpeg

Source: https://github.com/fujiwarachoki/supoclip/blob/main/backend/README.md

Install ffmpeg using package managers for macOS, Linux, or Windows.

```bash
# MacOS
brew install ffmpeg
```

```bash
# Linux (Ubuntu)
sudo apt update -y && sudo apt install install ffmpeg -y
```

```bash
# Windows (Chocolatey https://chocolatey.org/)
choco install ffmpeg
```

--------------------------------

### Start Local Database and Cache Services

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/development.md

Use docker-compose to start PostgreSQL and Redis for backend and frontend testing, or for a full-stack local environment.

```bash
docker-compose up -d postgres redis
```

```bash
docker-compose up -d
```

--------------------------------

### Install Backend Dependencies

Source: https://github.com/fujiwarachoki/supoclip/blob/main/backend/README.md

Install all backend dependencies using the uv package manager. This command installs dependencies for all groups.

```bash
uv sync --all-groups
```

--------------------------------

### Run Backend API Server

Source: https://github.com/fujiwarachoki/supoclip/blob/main/CLAUDE.md

Starts the FastAPI backend API server using uvicorn. Ensure PostgreSQL and Redis are running, and Python 3.11+ is installed.

```bash
cd backend
uv venv .venv && source .venv/bin/activate
uv sync
uvicorn src.main_refactored:app --reload --host 0.0.0.0 --port 8000
```

--------------------------------

### Start Full-Stack Services with Docker Compose

Source: https://github.com/fujiwarachoki/supoclip/blob/main/AGENTS.md

Use this command to build and start all services including frontend, backend, worker, Postgres, and Redis for full-stack development.

```bash
docker-compose up -d --build
```

--------------------------------

### Create and Activate Virtual Environment with uv

Source: https://github.com/fujiwarachoki/supoclip/blob/main/backend/README.md

Create a virtual environment using uv and activate it. Ensure uv is installed.

```bash
uv venv .venv
source .venv/bin/activate
```

--------------------------------

### Create and Configure .env File

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/setup.md

Copy the example environment file and set your API keys and configuration variables. Ensure at least `ASSEMBLY_AI_API_KEY`, `LLM`, `GOOGLE_API_KEY`, `BETTER_AUTH_SECRET`, and `BACKEND_AUTH_SECRET` are configured.

```bash
cp .env.example .env
```

```env
ASSEMBLY_AI_API_KEY=your_assemblyai_key
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=your_google_key
BETTER_AUTH_SECRET=replace_this_for_real_use
BACKEND_AUTH_SECRET=replace_this_if_using_hosted_mode

# Optional: DataFast analytics
NEXT_PUBLIC_DATAFAST_WEBSITE_ID=dfid_xxxxx
NEXT_PUBLIC_DATAFAST_DOMAIN=your-domain.com
NEXT_PUBLIC_DATAFAST_ALLOW_LOCALHOST=false
```

--------------------------------

### Docker Compose Deployment

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Deploy SupoClip using Docker Compose for a self-hosted setup. This involves cloning the repository, configuring the .env file, and starting the services.

```bash
# Clone and configure
git clone https://github.com/your-username/supoclip.git
cd supoclip
cp .env.example .env
# Edit .env with your API keys

# Start all services
docker-compose up -d

# Services started:
# - Frontend: http://localhost:3000
# - Backend API: http://localhost:8000 (docs at /docs)
# - PostgreSQL: localhost:5432
# - Redis: localhost:6379

# Monitor logs
docker-compose logs -f

# Run tests
make test           # All tests
make test-backend   # Backend only
make test-frontend  # Frontend only
make test-e2e       # End-to-end tests
```

--------------------------------

### Start SupoClip Manually with Docker Compose

Source: https://github.com/fujiwarachoki/supoclip/blob/main/QUICKSTART.md

Use these Docker Compose commands to manage SupoClip services directly. This includes starting, viewing logs, stopping, and rebuilding services.

```bash
# Start all services
docker-compose up -d --build
```

```bash
# View logs
docker-compose logs -f
```

```bash
# Stop all services
docker-compose down
```

```bash
# Rebuild after code changes
docker-compose up -d --build
```

--------------------------------

### Start SupoClip Docker Stack

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/setup.md

Use the provided script for the fastest startup or the manual Docker Compose command. The `--build` flag ensures images are built if necessary.

```bash
./start.sh
```

```bash
docker-compose up -d --build
```

--------------------------------

### Start Docker Services

Source: https://github.com/fujiwarachoki/supoclip/blob/main/CLAUDE.md

Use these commands to manage Docker services for the SupoClip project. Rebuild images if you make changes to the code.

```bash
docker-compose up -d
```

```bash
docker-compose up -d --build
```

```bash
docker-compose logs -f backend
```

```bash
docker-compose logs -f worker
```

```bash
docker-compose down
```

--------------------------------

### Run Next.js Development Server

Source: https://github.com/fujiwarachoki/supoclip/blob/main/AGENTS.md

Starts the Next.js development server for either the main frontend app or the waitlist app. Ensure you are in the respective directory.

```bash
cd frontend && npm run dev
```

```bash
cd waitlist && npm run dev
```

--------------------------------

### Clone SupoClip Repository

Source: https://github.com/fujiwarachoki/supoclip/blob/main/README.md

Clone the SupoClip repository to your local machine to begin the setup process. Navigate into the cloned directory to proceed with configuration.

```bash
git clone https://github.com/your-username/supoclip.git
cd supoclip
```

--------------------------------

### Frontend Development Commands

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/development.md

Navigate to the frontend directory and use these npm commands for development, building, starting, and linting the Next.js application.

```bash
cd frontend
npm install
npm run dev
npm run build
npm run start
npm run lint
```

--------------------------------

### Get Caption Templates

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Lists available caption style templates with their configurations, including font, color, and animation settings.

```bash
curl -X GET http://localhost:8000/caption-templates
```

--------------------------------

### Run Frontend Tests

Source: https://github.com/fujiwarachoki/supoclip/blob/main/README.md

Execute frontend route and component tests using Vitest and Testing Library. Ensure Node.js and npm are installed.

```bash
cd frontend && npm install && npm run test:coverage
```

--------------------------------

### Start SupoClip Services with Docker Compose

Source: https://github.com/fujiwarachoki/supoclip/blob/main/README.md

Launch the SupoClip application services, including the frontend, backend API, PostgreSQL, and Redis, using Docker Compose. This command runs the services in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### GET /caption-templates

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Retrieves a list of available caption style templates and their configurations.

```APIDOC
## GET /caption-templates

### Description
Lists available caption style templates with their configurations.

### Method
GET

### Endpoint
http://localhost:8000/caption-templates

### Response
#### Success Response (200)
- **templates** (array) - A list of caption templates.
  - **id** (string) - The unique identifier for the template.
  - **name** (string) - The display name of the template.
  - **description** (string) - A brief description of the template's style.
  - **animation** (string) - The type of text animation applied.
  - **font_family** (string) - The font family used in the template.
  - **font_size** (integer) - The font size.
  - **font_color** (string) - The font color in hexadecimal format.
  - **highlight_color** (string) - The highlight color in hexadecimal format.

### Response Example
{
  "templates": [
    {
      "id": "default",
      "name": "Default",
      "description": "Clean white text with black outline",
      "animation": "none",
      "font_family": "THEBOLDFONT",
      "font_size": 28,
      "font_color": "#FFFFFF",
      "highlight_color": "#FFD700"
    },
    {
      "id": "hormozi",
      "name": "Hormozi",
      "description": "Bold green highlights like Alex Hormozi's videos",
      "animation": "karaoke",
      "font_family": "THEBOLDFONT",
      "font_size": 36,
      "font_color": "#FFFFFF",
      "highlight_color": "#00FF00"
    },
    {
      "id": "mrbeast",
      "name": "MrBeast",
      "description": "Large yellow text with red highlights",
      "animation": "pop",
      "font_family": "THEBOLDFONT",
      "font_size": 42,
      "font_color": "#FFFF00",
      "highlight_color": "#FF0000"
    },
    {
      "id": "tiktok",
      "name": "TikTok",
      "description": "TikTok-style with pink highlights",
      "animation": "karaoke",
      "font_family": "TikTokSans-Regular",
      "font_size": 32,
      "font_color": "#FFFFFF",
      "highlight_color": "#FE2C55"
    }
  ]
}
```

--------------------------------

### Run Backend Worker Process

Source: https://github.com/fujiwarachoki/supoclip/blob/main/CLAUDE.md

Starts the ARQ worker process for handling background video processing tasks.

```bash
cd backend
arq src.workers.tasks.WorkerSettings
```

--------------------------------

### Provider Mismatch Examples

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/troubleshooting.md

Illustrates common API key requirements based on the selected LLM provider. Ensure the correct API key is set for the chosen LLM.

```text
LLM=openai:... requires OPENAI_API_KEY
LLM=google-gla:... requires GOOGLE_API_KEY
LLM=anthropic:... requires ANTHROPIC_API_KEY
LLM=ollama:... requires a reachable Ollama endpoint
```

--------------------------------

### Restart SupoClip Services After .env Changes

Source: https://github.com/fujiwarachoki/supoclip/blob/main/QUICKSTART.md

Apply changes made to the .env file by stopping and then starting the Docker Compose services.

```bash
docker-compose down
docker-compose up -d
```

--------------------------------

### Run FastAPI API Locally

Source: https://github.com/fujiwarachoki/supoclip/blob/main/AGENTS.md

Starts the FastAPI backend API server for local development. It enables hot-reloading for immediate feedback on code changes.

```bash
cd backend && uv sync && uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
```

--------------------------------

### Get Billing Summary

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Retrieves monetization status and current usage for the authenticated user. Responses vary based on self-hosted, hosted Pro, or hosted Free plans.

```bash
curl -X GET http://localhost:8000/tasks/billing/summary \
  -H "user_id: user_abc123"
```

--------------------------------

### Get Available Fonts

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Lists all available fonts, including system and user-uploaded custom fonts. Requires a 'user_id' header.

```bash
curl -X GET http://localhost:8000/fonts \
  -H "user_id: user_abc123"
```

--------------------------------

### Example Commit Message Format

Source: https://github.com/fujiwarachoki/supoclip/blob/main/AGENTS.md

Follow this format for commit messages to maintain consistency. It includes a type, optional scope, and a concise summary of the change.

```git
feat(backend): add task list pagination
```

--------------------------------

### Get Task Details

Source: https://github.com/fujiwarachoki/supoclip/blob/main/backend/REFACTORING_GUIDE.md

Retrieve the details of a specific task by sending a GET request to the /tasks/{task_id} endpoint.

```bash
curl http://localhost:8000/tasks/{task_id}
```

--------------------------------

### Get Generated Clips for a Task

Source: https://github.com/fujiwarachoki/supoclip/blob/main/backend/REFACTORING_GUIDE.md

Retrieve the list of generated clips for a specific task by sending a GET request to the /tasks/{task_id}/clips endpoint.

```bash
curl http://localhost:8000/tasks/{task_id}/clips
```

--------------------------------

### GET /broll/status

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Checks the configuration status of the B-roll integration (e.g., Pexels).

```APIDOC
## GET /broll/status

### Description
Checks if B-roll integration (Pexels) is configured.

### Method
GET

### Endpoint
http://localhost:8000/broll/status

### Response
#### Success Response (200)
- **configured** (boolean) - Indicates if the B-roll integration is configured.
- **provider** (string) - The name of the B-roll provider (e.g., pexels).

### Response Example
{
  "configured": true,
  "provider": "pexels"
}
```

--------------------------------

### Build Frontend Application

Source: https://github.com/fujiwarachoki/supoclip/blob/main/CLAUDE.md

Generates Prisma client and builds the Next.js application for production.

```bash
cd frontend
npm run build
```

--------------------------------

### Get Task Clips

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Retrieves all clips for a specific task with virality scores.

```APIDOC
## GET /tasks/{taskId}/clips

### Description
Retrieves all clips for a specific task with virality scores.

### Method
GET

### Endpoint
/tasks/{taskId}/clips

### Headers
- **user_id** (string) - Required - The ID of the user performing the action.

### Path Parameters
- **taskId** (string) - Required - The ID of the task whose clips are to be retrieved.

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the task.
- **clips** (array) - An array of clip objects.
  - **id** (string) - The ID of the clip.
  - **filename** (string) - The filename of the clip.
  - **file_path** (string) - The file path of the clip.
  - **start_time** (string) - The start time of the clip (HH:MM).
  - **end_time** (string) - The end time of the clip (HH:MM).
  - **duration** (number) - The duration of the clip in seconds.
  - **text** (string) - The transcript text for the clip segment.
  - **relevance_score** (number) - The relevance score of the clip.
  - **reasoning** (string) - The reasoning behind the relevance score.
  - **clip_order** (integer) - The order of the clip within the task.
  - **video_url** (string) - The URL to access the clip video.
  - **virality_score** (integer) - The calculated virality score.
  - **hook_score** (integer) - The hook score.
  - **engagement_score** (integer) - The engagement score.
  - **value_score** (integer) - The value score.
  - **shareability_score** (integer) - The shareability score.
  - **hook_type** (string) - The type of hook used in the clip.
- **total_clips** (integer) - The total number of clips for the task.

### Response Example
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "clips": [
    {
      "id": "clip_001",
      "filename": "clip_1_0225-0315.mp4",
      "file_path": "/temp/clips/clip_1_0225-0315.mp4",
      "start_time": "02:25",
      "end_time": "03:15",
      "duration": 50.0,
      "text": "The transcript text for this segment...",
      "relevance_score": 0.95,
      "reasoning": "Strong hook with surprising statistic",
      "clip_order": 1,
      "video_url": "/clips/clip_1_0225-0315.mp4",
      "virality_score": 85,
      "hook_score": 22,
      "engagement_score": 21,
      "value_score": 23,
      "shareability_score": 19,
      "hook_type": "statistic"
    }
  ],
  "total_clips": 5
}
```
```

--------------------------------

### Run Frontend Tests (Repo-level)

Source: https://github.com/fujiwarachoki/supoclip/blob/main/README.md

Execute frontend tests from the repository root.

```bash
make test-frontend
```

--------------------------------

### GET /fonts

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Lists all available fonts, including system and user-uploaded custom fonts.

```APIDOC
## GET /fonts

### Description
Lists all available fonts including system fonts and user-uploaded custom fonts.

### Method
GET

### Endpoint
http://localhost:8000/fonts

### Parameters
#### Headers
- **user_id** (string) - Required - The ID of the user.

### Response
#### Success Response (200)
- **fonts** (array) - A list of available fonts.
  - **name** (string) - The internal name of the font.
  - **display_name** (string) - The display name of the font.
  - **filename** (string) - The filename of the font.
  - **format** (string) - The font file format (e.g., ttf, otf).
  - **scope** (string) - The scope of the font (e.g., system, user).

### Response Example
{
  "fonts": [
    {
      "name": "TikTokSans-Regular",
      "display_name": "Tiktok Sans Regular",
      "filename": "TikTokSans-Regular.ttf",
      "format": "ttf",
      "scope": "system"
    },
    {
      "name": "THEBOLDFONT",
      "display_name": "The Bold Font",
      "filename": "THEBOLDFONT.ttf",
      "format": "ttf",
      "scope": "system"
    },
    {
      "name": "user_abc123_CustomFont",
      "display_name": "Custom Font",
      "filename": "user_abc123_CustomFont.ttf",
      "format": "ttf",
      "scope": "user"
    }
  ]
}
```

--------------------------------

### Run End-to-End Tests

Source: https://github.com/fujiwarachoki/supoclip/blob/main/README.md

Execute end-to-end browser tests using Playwright. Ensure Node.js and npm are installed.

```bash
cd frontend && npm run test:e2e
```

--------------------------------

### Trim Clip

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Adjusts clip boundaries by specifying start and end offsets (in seconds), then regenerates the clip file.

```APIDOC
## PATCH /tasks/{taskId}/clips/{clipId}

### Description
Adjusts clip boundaries by specifying start and end offsets (in seconds), then regenerates the clip file.

### Method
PATCH

### Endpoint
/tasks/{taskId}/clips/{clipId}

### Headers
- **Content-Type** (string) - Required - Application JSON.
- **user_id** (string) - Required - The ID of the user performing the action.

### Path Parameters
- **taskId** (string) - Required - The ID of the task the clip belongs to.
- **clipId** (string) - Required - The ID of the clip to trim.

### Request Body
- **start_offset** (number) - Required - The new start offset in seconds.
- **end_offset** (number) - Required - The new end offset in seconds.

### Request Example
```json
{
  "start_offset": 2.5,
  "end_offset": 3.0
}
```

### Response
#### Success Response (200)
- **clip** (object) - Details of the trimmed clip.
  - **id** (string) - The ID of the clip.
  - **filename** (string) - The new filename of the trimmed clip.
  - **duration** (number) - The new duration of the clip in seconds.
  - **start_time** (string) - The new start time of the clip (HH:MM).
  - **end_time** (string) - The new end time of the clip (HH:MM).

### Response Example
```json
{
  "clip": {
    "id": "clip_001",
    "filename": "trim_abc123def456.mp4",
    "duration": 44.5,
    "start_time": "02:27",
    "end_time": "03:12"
  }
}
```
```

--------------------------------

### Configure Environment Variables for SupoClip

Source: https://github.com/fujiwarachoki/supoclip/blob/main/QUICKSTART.md

Edit the .env file to add your API keys for transcription and AI providers, and configure the LLM model. Uncomment lines for Ollama or Resend if needed.

```bash
# Required for video transcription
ASSEMBLY_AI_API_KEY=your_assemblyai_key_here

# Choose one AI provider for clip selection
OPENAI_API_KEY=your_openai_key_here

# Configure which AI model to use
LLM=openai:gpt-4

# OR use Ollama locally
# LLM=ollama:gpt-oss:20b
# OLLAMA_BASE_URL=http://localhost:11434/v1

# Optional: Resend for waitlist + subscription lifecycle emails
# Required if you want hosted billing emails when SELF_HOST=false
# RESEND_API_KEY=your_resend_api_key_here
# RESEND_FROM_EMAIL="SupoClip <onboarding@your-domain.com>"
```

--------------------------------

### Run All Tests (Repo-level)

Source: https://github.com/fujiwarachoki/supoclip/blob/main/README.md

Execute all test suites (backend, frontend, e2e, CI) from the repository root.

```bash
make test
```

--------------------------------

### Task API - Get Task Progress (SSE)

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Subscribes to real-time progress updates for a task via Server-Sent Events.

```APIDOC
## GET /tasks/{task_id}/progress

### Description
Subscribes to real-time progress updates for a task via Server-Sent Events.

### Method
GET

### Endpoint
/tasks/{task_id}/progress

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the task to track progress for.

### Response
#### Success Response (200)
Server-Sent Events stream with updates on task status and progress.
- **event: status**
  - **data** (object) - Contains task status information.
    - **task_id** (string) - The ID of the task.
    - **status** (string) - The current status of the task (e.g., 'processing').
    - **progress** (integer) - The completion percentage of the task.
    - **message** (string) - A message describing the current progress.
- **event: progress**
  - **data** (object) - Contains detailed progress information.
    - **progress** (integer) - The completion percentage of the task.
    - **message** (string) - A message describing the current progress.
- **event: close**
  - **data** (object) - Indicates the task has finished or been closed.
    - **status** (string) - The final status of the task.

### Request Example
```javascript
const eventSource = new EventSource(
  'http://localhost:8000/tasks/550e8400-e29b-41d4-a716-446655440000/progress',
  { headers: { 'user_id': 'user_abc123' } }
);

eventSource.addEventListener('status', (event) => {
  const data = JSON.parse(event.data);
  console.log(`Status: ${data.status}, Progress: ${data.progress}%`);
  // { task_id: "...", status: "processing", progress: 45, message: "Generating clips..." }
});

eventSource.addEventListener('progress', (event) => {
  const data = JSON.parse(event.data);
  console.log(`Progress: ${data.progress}% - ${data.message}`);
});

eventSource.addEventListener('close', (event) => {
  const data = JSON.parse(event.data);
  console.log(`Task ${data.status}`);
  eventSource.close();
});
```
```

--------------------------------

### Task API - Get Task Details

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Retrieves complete task information including generated clips with virality scores.

```APIDOC
## GET /tasks/{task_id}

### Description
Retrieves complete task information including generated clips with virality scores.

### Method
GET

### Endpoint
/tasks/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the task to retrieve.

### Response
#### Success Response (200)
- **id** (string) - Task ID.
- **user_id** (string) - User ID associated with the task.
- **source_title** (string) - Title of the source video.
- **source_type** (string) - Type of the source (e.g., 'youtube').
- **status** (string) - Current status of the task (e.g., 'completed').
- **clips** (array) - List of generated clips.
  - **id** (string) - Clip ID.
  - **filename** (string) - Filename of the clip.
  - **start_time** (string) - Start time of the clip in the source video.
  - **end_time** (string) - End time of the clip in the source video.
  - **duration** (number) - Duration of the clip in seconds.
  - **text** (string) - Transcript text of the clip.
  - **relevance_score** (number) - Score indicating the relevance of the clip.
  - **reasoning** (string) - Explanation for the clip's selection.
  - **virality_score** (integer) - Predicted virality score.
  - **hook_score** (integer) - Score for the clip's hook.
  - **engagement_score** (integer) - Score for potential engagement.
  - **value_score** (integer) - Score for the value provided by the clip.
  - **shareability_score** (integer) - Score for the clip's shareability.
  - **hook_type** (string) - Type of hook used.
  - **video_url** (string) - URL to access the generated clip video.
- **clips_count** (integer) - Total number of clips generated for the task.

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user_abc123",
  "source_title": "My Long Video",
  "source_type": "youtube",
  "status": "completed",
  "clips": [
    {
      "id": "clip_001",
      "filename": "clip_1_0225-0315.mp4",
      "start_time": "02:25",
      "end_time": "03:15",
      "duration": 50.0,
      "text": "The most important thing about...",
      "relevance_score": 0.95,
      "reasoning": "Strong hook with actionable insight",
      "virality_score": 85,
      "hook_score": 22,
      "engagement_score": 21,
      "value_score": 23,
      "shareability_score": 19,
      "hook_type": "statement",
      "video_url": "/clips/clip_1_0225-0315.mp4"
    }
  ],
  "clips_count": 5
}
```
```

--------------------------------

### Run Backend Tests (Repo-level)

Source: https://github.com/fujiwarachoki/supoclip/blob/main/README.md

Execute backend tests from the repository root.

```bash
make test-backend
```

--------------------------------

### Frontend Build with Prisma Generation

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/development.md

This command generates Prisma client code and builds the Next.js application. Prisma generation is also run during `postinstall`.

```bash
prisma generate && next build
```

--------------------------------

### Minimal Self-Hosted .env Configuration

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/configuration.md

Essential environment variables for running SupoClip in a basic self-hosted mode. Requires API keys for AssemblyAI and Google services, and a secret for Better Auth.

```env
ASSEMBLY_AI_API_KEY=your_key
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=your_key
BETTER_AUTH_SECRET=replace_me
SELF_HOST=true
```

--------------------------------

### SupoClip Environment Configuration

Source: https://github.com/fujiwarachoki/supoclip/blob/main/README.md

Configure the SupoClip application by creating a `.env` file in the root directory. This file holds essential API keys for transcription, LLM providers, and optional settings for authentication, analytics, and email services. Ensure you replace placeholder values with your actual API keys.

```env
# Required: Video transcription
ASSEMBLY_AI_API_KEY=your_assemblyai_api_key

# Required: Choose ONE LLM provider and set its API key
# Option A: Google Gemini (recommended - fast & cost-effective)
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=your_google_api_key

# Option B: OpenAI GPT-5.2 (best reasoning)
# LLM=openai:gpt-5.2
# OPENAI_API_KEY=your_openai_api_key

# Option C: Anthropic Claude
# LLM=anthropic:claude-4-sonnet
# ANTHROPIC_API_KEY=your_anthropic_api_key

# Option D: Ollama (local/self-hosted)
# LLM=ollama:gpt-oss:20b
# OLLAMA_BASE_URL=http://localhost:11434/v1
# OLLAMA_API_KEY=your_ollama_api_key  # Optional (Ollama Cloud)

# Optional: Auth secret (change in production)
BETTER_AUTH_SECRET=change_this_in_production

# Optional: DataFast analytics
# Track your deployed domain in DataFast
# NEXT_PUBLIC_DATAFAST_WEBSITE_ID=dfid_xxxxx
# NEXT_PUBLIC_DATAFAST_DOMAIN=your-domain.com
# NEXT_PUBLIC_DATAFAST_ALLOW_LOCALHOST=false

# Optional: Resend for waitlist confirmation emails
# RESEND_API_KEY=your_resend_api_key

# Optional: YouTube metadata provider
# `yt_dlp` preserves the existing metadata behavior
# `youtube_data_api` uses the official API first, then falls back to yt-dlp
# YOUTUBE_METADATA_PROVIDER=yt_dlp
# YOUTUBE_DATA_API_KEY=your_youtube_data_api_key
```

--------------------------------

### Run Arq Worker Locally

Source: https://github.com/fujiwarachoki/supoclip/blob/main/AGENTS.md

Starts the Arq worker process, which is responsible for background task processing. Ensure you are in the backend directory.

```bash
cd backend && .venv/bin/arq src.workers.tasks.WorkerSettings
```

--------------------------------

### Create a Task for Video Processing

Source: https://github.com/fujiwarachoki/supoclip/blob/main/backend/REFACTORING_GUIDE.md

Create a new task for video processing by sending a POST request to the /tasks/ endpoint. Requires Content-Type and user_id headers, and a JSON body with source URL and font options.

```bash
curl -X POST http://localhost:8000/tasks/ \
  -H "Content-Type: application/json" \
  -H "user_id: YOUR_USER_ID" \
  -d '{
    "source": {
      "url": "https://www.youtube.com/watch?v=VIDEO_ID"
    },
    "font_options": {
      "font_family": "TikTokSans-Regular",
      "font_size": 24,
      "font_color": "#FFFFFF"
    }
  }'
```

--------------------------------

### Run End-to-End Tests (Repo-level)

Source: https://github.com/fujiwarachoki/supoclip/blob/main/README.md

Execute end-to-end tests from the repository root.

```bash
make test-e2e
```

--------------------------------

### Trim Clip File (Python)

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Trims a video clip by removing a specified duration from the start and end. Returns the path to the trimmed file.

```python
from pathlib import Path
from backend.src.clip_editor import (
    trim_clip_file,
    split_clip_file,
    merge_clip_files,
    overlay_custom_captions,
    export_with_preset,
    EXPORT_PRESETS
)

output_dir = Path("/output/edited")

# Trim a clip (remove 2.5s from start, 3s from end)
trimmed_path = trim_clip_file(
    input_path=Path("/clips/original.mp4"),
    output_dir=output_dir,
    start_offset=2.5,
    end_offset=3.0
)
```

--------------------------------

### Run CI Tests (Repo-level)

Source: https://github.com/fujiwarachoki/supoclip/blob/main/README.md

Execute tests as configured for Continuous Integration from the repository root.

```bash
make test-ci
```

--------------------------------

### Apply Database Migration

Source: https://github.com/fujiwarachoki/supoclip/blob/main/backend/REFACTORING_GUIDE.md

Apply the database migration to add progress fields to the tasks table. This command assumes you have Docker and psql installed and configured.

```bash
docker exec -i supoclip-postgres psql -U postgres -d supoclip < backend/migrations/001_add_progress_fields.sql
```

--------------------------------

### Environment Variables Configuration

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Configure SupoClip by setting environment variables in a .env file. This includes API keys for transcription and LLM providers, database credentials, and processing settings.

```bash
# Required: Video transcription
ASSEMBLY_AI_API_KEY=your_assemblyai_api_key

# Required: Choose ONE LLM provider
# Option A: Google Gemini (recommended)
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=your_google_api_key

# Option B: OpenAI
# LLM=openai:gpt-5.2
# OPENAI_API_KEY=your_openai_api_key

# Option C: Anthropic Claude
# LLM=anthropic:claude-4-sonnet
# ANTHROPIC_API_KEY=your_anthropic_api_key

# Option D: Ollama (local)
# LLM=ollama:gpt-oss:20b
# OLLAMA_BASE_URL=http://localhost:11434/v1

# Database and Cache
DATABASE_URL=postgresql://user:password@localhost:5432/supoclip
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=optional_password

# Processing settings
DEFAULT_PROCESSING_MODE=fast  # fast, balanced, quality
FAST_MODE_MAX_CLIPS=4
FAST_MODE_TRANSCRIPT_MODEL=nano  # nano or best
MAX_VIDEO_DURATION=5400  # seconds (90 minutes)
MAX_CLIPS=10

# Self-hosted vs Monetized
SELF_HOST=true  # Set to false for monetized hosted version
BACKEND_AUTH_SECRET=your_secret_for_monetized_mode

# Optional: B-roll integration
PEXELS_API_KEY=your_pexels_api_key

# Optional: YouTube metadata (faster than yt-dlp)
YOUTUBE_METADATA_PROVIDER=youtube_data_api
YOUTUBE_DATA_API_KEY=your_youtube_data_api_key

# Optional: Billing emails (hosted mode)
RESEND_API_KEY=your_resend_api_key
RESEND_FROM_EMAIL=SupoClip <noreply@yourdomain.com>

# Optional: Feedback webhooks
DISCORD_FEEDBACK_WEBHOOK_URL=https://discord.com/api/webhooks/...
```

--------------------------------

### Get Video Transcript (Python)

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Retrieves a transcript from a video file using a specified speech model. Use 'best' for accuracy or 'nano' for speed.

```python
from pathlib import Path
from backend.src.video_utils import (
    get_video_transcript,
    create_clips_from_segments,
    create_optimized_clip
)

# Get transcript with AssemblyAI
video_path = Path("/path/to/video.mp4")
transcript = get_video_transcript(video_path, speech_model="best")  # or "nano" for faster
```

--------------------------------

### Get Task Clips

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Retrieves all clips associated with a specific task, including their virality scores and other metadata. Requires a task ID and user ID.

```bash
curl -X GET http://localhost:8000/tasks/550e8400-e29b-41d4-a716-446655440000/clips \
  -H "user_id: user_abc123"
```

--------------------------------

### Export with Preset (Python)

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Exports a video clip using predefined platform-specific presets. Lists available presets.

```python
# Export with platform preset
print(f"Available presets: {list(EXPORT_PRESETS.keys())}")
```

--------------------------------

### Clone SupoClip Repository

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/setup.md

Use this command to clone the SupoClip repository. Replace `<your-repo-url>` with the actual URL.

```bash
git clone <your-repo-url>
cd supoclip
```

--------------------------------

### GET /tasks/billing/summary

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Retrieves the billing summary, including monetization status, plan details, and usage tracking for the authenticated user. This is relevant for the hosted monetized version.

```APIDOC
## GET /tasks/billing/summary

### Description
Retrieves monetization status and current usage for the authenticated user.

### Method
GET

### Endpoint
http://localhost:8000/tasks/billing/summary

### Parameters
#### Headers
- **user_id** (string) - Required - The ID of the user.

### Response
#### Success Response (200)
- **monetization_enabled** (boolean) - Whether monetization is enabled.
- **plan** (string) - The current subscription plan (e.g., free, pro, self_host).
- **subscription_status** (string) - The status of the subscription (e.g., active, inactive).
- **period_start** (string, optional) - The start date of the current billing period (ISO 8601 format).
- **period_end** (string, optional) - The end date of the current billing period (ISO 8601 format).
- **trial_ends_at** (string, optional) - The date when the trial period ends (ISO 8601 format).
- **usage_count** (integer) - The number of tasks or resources consumed.
- **usage_limit** (integer or null) - The limit for resource consumption, if applicable.
- **remaining** (integer or null) - The remaining resources available.
- **can_create_task** (boolean) - Whether the user can create new tasks based on their plan and usage.
- **upgrade_required** (boolean) - Indicates if an upgrade is necessary to perform certain actions.
- **reason** (string or null) - Provides a reason if `can_create_task` is false or `upgrade_required` is true.

### Response Examples
#### Self-hosted Response
{
  "monetization_enabled": false,
  "plan": "self_host",
  "subscription_status": "inactive",
  "usage_count": 0,
  "usage_limit": null,
  "remaining": null,
  "can_create_task": true,
  "upgrade_required": false,
  "reason": null
}

#### Hosted Mode - Pro Subscriber Response
{
  "monetization_enabled": true,
  "plan": "pro",
  "subscription_status": "active",
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z",
  "trial_ends_at": null,
  "usage_count": 15,
  "usage_limit": null,
  "remaining": null,
  "can_create_task": true,
  "upgrade_required": false,
  "reason": null
}

#### Hosted Mode - Free User Response
{
  "monetization_enabled": true,
  "plan": "free",
  "subscription_status": "inactive",
  "usage_count": 3,
  "usage_limit": null,
  "remaining": null,
  "can_create_task": false,
  "upgrade_required": true,
  "reason": "Active subscription required"
}
```

--------------------------------

### Trim Clip

Source: https://context7.com/fujiwarachoki/supoclip/llms.txt

Adjusts the start and end times of a specific clip by providing new offset values. This operation regenerates the clip file with the specified boundaries.

```bash
curl -X PATCH http://localhost:8000/tasks/550e8400-e29b-41d4-a716-446655440000/clips/clip_001 \
  -H "Content-Type: application/json" \
  -H "user_id: user_abc123" \
  -d 
    "{
      \"start_offset\": 2.5,
      \"end_offset\": 3.0
    }"
```

--------------------------------

### Build Backend Docker Image

Source: https://github.com/fujiwarachoki/supoclip/blob/main/backend/REFACTORING_GUIDE.md

Build the backend Docker image. This command automatically picks up new dependencies from pyproject.toml.

```bash
docker-compose build backend
```

--------------------------------

### Check Container Status and Logs

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/troubleshooting.md

Use these commands to check if containers are running and to view their logs. Useful for initial troubleshooting when the app is misbehaving.

```bash
docker-compose ps
```

```bash
docker-compose logs -f
```

```bash
docker-compose logs -f backend
```

```bash
docker-compose logs -f worker
```

--------------------------------

### Backend Test Environment Variables

Source: https://github.com/fujiwarachoki/supoclip/blob/main/docs/development.md

Configure these environment variables for backend integration and end-to-end testing. Ensure PostgreSQL and Redis are accessible.

```bash
DATABASE_URL=postgresql+asyncpg://localhost:5432/supoclip
TEST_DATABASE_URL=postgresql+asyncpg://localhost:5432/supoclip
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
BACKEND_AUTH_SECRET=supoclip_test_secret
BETTER_AUTH_SECRET=supoclip_better_auth_test_secret
```