### Install and Setup Cap Repository

Source: https://github.com/capsoftware/cap/blob/main/README.md

Run these commands to install dependencies and set up the local development environment for the Cap project.

```bash
pnpm install
pnpm env-setup
pnpm cap-setup
```

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

### Setup Project Environment

Source: https://github.com/capsoftware/cap/blob/main/AGENTS.md

Sets up the project environment after installation. This command should be run after `pnpm install`.

```bash
pnpm env-setup
pnpm cap-setup
```

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

### Install Dependencies and Setup Environment

Source: https://github.com/capsoftware/cap/blob/main/CONTRIBUTING.md

Run these commands to install project dependencies and set up the development environment, including generating a .env file.

```bash
pnpm install
pnpm env-setup
```

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

### Self-Host Cap with Docker Compose

Source: https://github.com/capsoftware/cap/blob/main/README.md

Clone the repository and start Cap services using Docker Compose for a quick self-hosted setup. Ensure Docker is installed.

```bash
git clone https://github.com/CapSoftware/Cap.git
cd Cap
docker compose up -d
```

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

### Install Native Dependencies

Source: https://github.com/capsoftware/cap/blob/main/CONTRIBUTING.md

Execute this command to install native dependencies required for the Cap project, such as FFmpeg.

```bash
pnpm cap-setup
```

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

### Install Cap CLI using Script

Source: https://github.com/capsoftware/cap/blob/main/apps/cli/README.md

Installs the Cap CLI using a shell script. For Windows, PowerShell and Command Prompt alternatives are provided. The script also handles the installation of Cap Desktop if it's not already present.

```sh
curl -fsSL https://cap.so/install-cli.sh | sh
```

```powershell
irm https://cap.so/install-cli.ps1 | iex
```

```cmd
curl.exe -fsSL https://cap.so/install-cli.cmd -o "%TEMP%\cap-install-cli.cmd" && "%TEMP%\cap-install-cli.cmd"
```

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

### Start Recording with Options

Source: https://github.com/capsoftware/cap/blob/main/apps/web/public/llms-full.txt

Starts a new recording with specified parameters like screen, mode, camera, mic, system audio, path, FPS, and duration. The --detach flag allows the recording to continue in the background.

```bash
cap record start --screen <id> --json
```

```bash
cap record start --screen <id> --detach --json
```

```bash
cap record start --window <id> --mode studio --camera <id> --mic <name> --system-audio --path <path> --fps <1-120> --duration <seconds> --detach --format <text|json>
```

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

### Install Project Dependencies

Source: https://github.com/capsoftware/cap/blob/main/AGENTS.md

Installs project dependencies using pnpm. Ensure you have pnpm installed and the environment is set up.

```bash
pnpm install
```

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

### Implement Display A/V Sync Logic

Source: https://github.com/capsoftware/cap/blob/main/crates/recording/FINDINGS.md

This code adds logic to synchronize the display's start time with the camera or microphone's start time if the drift exceeds 30ms. It prioritizes camera sync over microphone sync if both are available.

```rust
let raw_display_start = to_start_time(s.pipeline.screen.first_timestamp);
let display_start_time = if let Some(cam_start) = camera_start_time {
    let sync_offset = raw_display_start - cam_start;
    if sync_offset.abs() > 0.030 { cam_start } else { raw_display_start }
} else if let Some(mic_start) = mic_start_time {
    let sync_offset = raw_display_start - mic_start;
    if sync_offset.abs() > 0.030 { mic_start } else { raw_display_start }
} else {
    raw_display_start
};
```

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

### Cap CLI Install via Desktop

Source: https://github.com/capsoftware/cap/blob/main/apps/web/public/llms-full.txt

Installs the Cap CLI using a Cap Desktop command. This is an alternative to script-based installation.

```bash
cap desktop install-cli
```

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

### Install Cap CLI

Source: https://github.com/capsoftware/cap/blob/main/apps/web/public/llms-full.txt

Installs the Cap CLI using a shell script. For PowerShell, use the alternative command.

```bash
curl -fsSL https://cap.so/install-cli.sh | sh
```

```powershell
irm https://cap.so/install-cli.ps1 | iex
```

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

### Run Quick Playback Benchmark

Source: https://github.com/capsoftware/cap/blob/main/crates/editor/PLAYBACK-FINDINGS.md

Execute a quick playback benchmark to verify the current state of the system. This command is part of the initial setup for performance analysis.

```bash
cargo run -p cap-recording --example playback-test-runner -- full
```

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

### Install GTK for Linux (Debian/Ubuntu)

Source: https://github.com/capsoftware/cap/blob/main/vendor/tao/README.md

Install the GTK3 development packages on Debian or Ubuntu. This is a prerequisite for building TAO applications on these distributions.

```bash
sudo apt install libgtk-3-dev

```

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

### Install GTK for Linux (Arch)

Source: https://github.com/capsoftware/cap/blob/main/vendor/tao/README.md

Install the GTK3 development packages on Arch Linux or Manjaro. This is a prerequisite for building TAO applications on these distributions.

```bash
sudo pacman -S gtk3

```

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

### Sync System Audio Start Time

Source: https://github.com/capsoftware/cap/blob/main/crates/editor/PLAYBACK-FINDINGS.md

Synchronizes system audio start time to mic or display when drift exceeds 30ms, improving playback alignment in fragmented recordings.

```rust
crates/recording/src/studio_recording.rs: System audio start_time now syncs to mic (or display) when drift >30ms, matching the existing camera/display sync pattern. Improves playback alignment.
```

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

### Run Web Application from its Directory

Source: https://github.com/capsoftware/cap/blob/main/CONTRIBUTING.md

Navigate to the web app directory and run this command to start only the @cap/web NextJS application.

```bash
cd ./apps/web
pnpm dev
```

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

### Run Quick Export Benchmark

Source: https://github.com/capsoftware/cap/blob/main/crates/export/EXPORT-FINDINGS.md

Execute a quick benchmark run for the export functionality to verify the current state. This command is part of the initial setup when context resets.

```bash
cargo run -p cap-export --example export-benchmark-runner -- quick
```

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

### Check and Create Test Recordings

Source: https://github.com/capsoftware/cap/blob/main/crates/editor/PLAYBACK-FINDINGS.md

Use these commands to check for existing test recordings and create them if they are missing. Ensure you have the necessary environment setup before running.

```bash
# Check for existing recordings
ls /tmp/cap-real-device-tests/
```

```bash
# If none exist, create them first:
cargo run -p cap-recording --example real-device-test-runner -- baseline --keep-outputs
```

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

### Styled Responsive Embed

Source: https://github.com/capsoftware/cap/blob/main/apps/web/content/docs/sharing/embeds.mdx

This example demonstrates styling tips for embeds, including `max-width`, `margin`, `box-shadow`, and `border-radius` applied to the container.

```html
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 800px; margin: 2rem auto; box-shadow: 0 4px 12px rgba(0,0,0,0.1); border-radius: 12px;">
  <iframe
    src="https://cap.so/embed/[video-id]"
    frameborder="0"
    allowfullscreen
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border-radius: 12px;"
  ></iframe>
</div>
```

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

### List Videos Request Example

Source: https://github.com/capsoftware/cap/blob/main/apps/web/content/docs/api/rest-api.mdx

Example of a cURL request to list videos using the REST API. It includes pagination parameters and the required Authorization header.

```bash
curl https://cap.so/api/developer/v1/videos?limit=10 \
  -H "Authorization: Bearer csk_your_secret_key_here"
```

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

### Run Baseline Benchmark

Source: https://github.com/capsoftware/cap/blob/main/crates/recording/FINDINGS.md

Execute a quick, isolated benchmark test for MP4 recording. This is recommended for development to get reliable results.

```bash
cargo run -p cap-recording --example real-device-test-runner -- baseline --mp4-only --keep-outputs
```

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

### Setup Tinybird Analytics

Source: https://github.com/capsoftware/cap/blob/main/README.md

Deploy Tinybird datasources and pipes. This command manages analytics configuration and may remove external resources.

```bash
pnpm analytics:setup
```

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

### Check Cap CLI Availability

Source: https://github.com/capsoftware/cap/blob/main/apps/cli/skill/cap/SKILL.md

Verifies if the Cap CLI is installed and accessible. If not found, guides the user on installation and enabling the CLI.

```sh
cap doctor --json
```

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

### Get Video Response Example

Source: https://github.com/capsoftware/cap/blob/main/apps/web/content/docs/api/rest-api.mdx

Example JSON response for retrieving a single video by ID via the REST API. The response includes all details of the specified video.

```json
{
  "data": {
    "id": "abc123def456",
    "appId": "app_789",
    "externalUserId": "user_42",
    "name": "Product Demo",
    "duration": 124.5,
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "s3Key": "developer/app_789/abc123def456/result.mp4",
    "transcriptionStatus": "COMPLETE",
    "metadata": null,
    "deletedAt": null,
    "createdAt": "2025-06-15T10:30:00.000Z",
    "updatedAt": "2025-06-15T10:32:00.000Z"
  }
}
```

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

### Configure WGPU Module with Logging

Source: https://github.com/capsoftware/cap/blob/main/vendor/wgpu-hal/examples/raw-gles.em.html

Sets up the WGPU module, linking it to a canvas element and configuring environment variables for logging before the WGPU module runs. Ensure the 'canvas' element exists in your HTML.

```javascript
var Module = { canvas: document.getElementById("canvas"), preRun: [function() {ENV.RUST_LOG = "debug"}] };
```

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

### Get Video Request Example

Source: https://github.com/capsoftware/cap/blob/main/apps/web/content/docs/api/rest-api.mdx

Example cURL request to retrieve a specific video by its ID using the REST API. Ensure you include your secret key in the Authorization header.

```bash
curl https://cap.so/api/developer/v1/videos/abc123def456 \
  -H "Authorization: Bearer csk_your_secret_key_here"
```

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

### Run Full Benchmark Suite (No Camera)

Source: https://github.com/capsoftware/cap/blob/main/crates/recording/FINDINGS.md

Execute the complete benchmark suite without the camera input, which results in a faster test duration.

```bash
cargo run -p cap-recording --example real-device-test-runner -- full --no-camera --keep-outputs
```

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

### Start Fixed-Length Screen Recording

Source: https://github.com/capsoftware/cap/blob/main/apps/cli/skill/cap/SKILL.md

Starts a screen recording for a predefined duration without detaching from the terminal.

```sh
cap record start --screen <id> --duration 10 --json
```

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

### Run Cap Export Benchmarks

Source: https://github.com/capsoftware/cap/blob/main/crates/export/EXPORT-BENCHMARKS.md

Execute benchmark tests for the Cap export system. Use 'quick' for a subset of presets, 'full' for all presets, or specify 'mp4-only' or 'gif-only'. Add '--benchmark-output' to write results to a file. Custom durations can be set with '--duration'.

```bash
cargo run -p cap-export --example export-benchmark-runner -- quick
```

```bash
cargo run -p cap-export --example export-benchmark-runner -- full --benchmark-output
```

```bash
cargo run -p cap-export --example export-benchmark-runner -- mp4-only --benchmark-output
```

```bash
cargo run -p cap-export --example export-benchmark-runner -- gif-only --benchmark-output
```

```bash
cargo run -p cap-export --example export-benchmark-runner -- full --duration 60 --benchmark-output
```

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

### Build and Test cap-rendering-skia

Source: https://github.com/capsoftware/cap/blob/main/crates/rendering-skia/README.md

Commands to build the crate, run the test binary, and execute tests for the cap-rendering-skia project.

```bash
cargo build -p cap-rendering-skia
```

```bash
cargo run -p cap-rendering-skia --bin test-skia
```

```bash
cargo test -p cap-rendering-skia
```

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

### Run Full Benchmark Suite

Source: https://github.com/capsoftware/cap/blob/main/crates/recording/FINDINGS.md

Execute the complete benchmark suite. This test takes approximately one minute and may be affected by thermal throttling.

```bash
cargo run -p cap-recording --example real-device-test-runner -- full --keep-outputs --benchmark-output
```

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

### Typical Agent Workflow with Cap CLI

Source: https://github.com/capsoftware/cap/blob/main/apps/cli/README.md

Demonstrates a common sequence of commands for recording, validating, and exporting a project using the Cap CLI. Use `--json` for machine-readable output.

```sh
cap doctor --json                          # verify permissions & capture readiness (exits 0; read `ok`/`captureReady`)
```

```sh
cap targets --json                         # discover screens/windows/cameras/mics (ids feed the next steps)
```

```sh
cap record start --screen <id> --json --detach  # start in the background -> {"type":"started","recordingId","pid","path"}
```

```sh
# ... the agent performs whatever it needs to capture ...
```

```sh
cap record stop --id <recordingId> --json  # finalize -> {"type":"stopped","path","recordingMetaExists":true}
```

```sh
cap project validate <path.cap> --json     # confirm the recording is complete before exporting
```

```sh
cap export <path.cap> --output out.mp4 --json
```

```sh
cap upload out.mp4 --json                   # -> {"type":"uploaded","id","link"} (auto-auth via Cap Desktop)
```

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

### Get Presigned Part URL

Source: https://github.com/capsoftware/cap/blob/main/apps/web/content/docs/api/rest-api.mdx

Get a presigned URL to upload a single part of a video file during a multipart upload using the SDK API.

```APIDOC
## POST /api/developer/sdk/v1/upload/multipart/presign-part

### Description
Get a presigned URL to upload a single part.

### Method
POST

### Endpoint
/api/developer/sdk/v1/upload/multipart/presign-part

### Parameters
#### Request Body
- **videoId** (string) - Required - The video ID
- **uploadId** (string) - Required - The upload ID from the initiate step
- **partNumber** (number) - Required - Part number (starting from 1)

### Response
#### Success Response (200)
- **presignedUrl** (string) - The presigned URL for uploading a part.

### Response Example
```json
{
  "presignedUrl": "https://s3.amazonaws.com/..."
}
```
```

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

### Database Generation and Migration

Source: https://github.com/capsoftware/cap/blob/main/AGENTS.md

Commands to generate, push, and access the database studio. Ensure the database is running before pushing.

```bash
pnpm db:generate
pnpm db:push
pnpm db:studio
```

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

### List Videos Response Example

Source: https://github.com/capsoftware/cap/blob/main/apps/web/content/docs/api/rest-api.mdx

Example JSON response when listing videos via the REST API. It contains an array of video objects, each with detailed metadata.

```json
{
  "data": [
    {
      "id": "abc123def456",
      "appId": "app_789",
      "externalUserId": "user_42",
      "name": "Product Demo",
      "duration": 124.5,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "s3Key": "developer/app_789/abc123def456/result.mp4",
      "transcriptionStatus": "COMPLETE",
      "metadata": null,
      "deletedAt": null,
      "createdAt": "2025-06-15T10:30:00.000Z",
      "updatedAt": "2025-06-15T10:32:00.000Z"
    }
  ]
}
```

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

### Run Live Playback Benchmark Harness

Source: https://github.com/capsoftware/cap/blob/main/crates/editor/PLAYBACK-FINDINGS.md

Execute the live playback benchmark harness with specified recording path, frames per second, and resolution. This command is used for validation.

```bash
cargo run -p cap-editor --example editor-playback-benchmark -- --recording-path /tmp/cap-performance-fixtures/reference-recording.cap --fps 60 --frames 300 --resolution full
```

```bash
cargo run -p cap-editor --example editor-playback-benchmark -- --recording-path /tmp/cap-performance-fixtures/reference-recording.cap --fps 60 --frames 300 --resolution half
```

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

### Enable AI Features with API Keys

Source: https://github.com/capsoftware/cap/blob/main/apps/web/content/docs/self-hosting.mdx

Set these environment variables to enable AI-powered features like video transcription and summaries. Groq is preferred for summaries, with OpenAI as a fallback.

```bash
DEEPGRAM_API_KEY=your-key    # Transcription
GROQ_API_KEY=your-key        # AI summaries (preferred)
OPENAI_API_KEY=your-key      # AI summaries (fallback)
```

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

### Cap CLI Authentication JSON Output Example

Source: https://github.com/capsoftware/cap/blob/main/apps/cli/README.md

Example JSON output from `cap auth status --json`. This format provides structured information about the authentication state, including whether authentication is active, its source, the server address, and the user identifier.

```json
{"authenticated":true,"source":"desktop","server":"…","userId":"…"}
```

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

### Create Video SDK Endpoint

Source: https://github.com/capsoftware/cap/blob/main/apps/web/content/docs/api/rest-api.mdx

Create a new video record and obtain sharing and embedding URLs. This endpoint requires a public key in the Authorization header. A `402` error is returned if the app has insufficient credits.

```bash
POST /api/developer/sdk/v1/videos/create
```

```bash
curl -X POST https://cap.so/api/developer/sdk/v1/videos/create \
  -H "Authorization: Bearer cpk_your_public_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "User Recording", "userId": "user_42"}'
```

```json
{
  "videoId": "abc123def456",
  "s3Key": "developer/app_789/abc123def456/result.mp4",
  "shareUrl": "https://cap.so/dev/abc123def456",
  "embedUrl": "https://cap.so/embed/abc123def456?sdk=1"
}
```

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

### Get Video

Source: https://github.com/capsoftware/cap/blob/main/apps/web/content/docs/api/rest-api.mdx

Retrieve a single video by its unique ID.

```APIDOC
## GET /api/developer/v1/videos/:id

### Description
Retrieve a single video by ID.

### Method
GET

### Endpoint
/api/developer/v1/videos/:id

### Parameters
#### Path Parameters
- **id** (string) - The video ID

### Request Example
```bash
curl https://cap.so/api/developer/v1/videos/abc123def456 \
  -H "Authorization: Bearer csk_your_secret_key_here"
```

### Response
#### Success Response (200)
- **data** (object) - The video object.
  - **id** (string) - The video ID.
  - **appId** (string) - The application ID.
  - **externalUserId** (string) - The external user ID.
  - **name** (string) - The name of the video.
  - **duration** (number) - The duration of the video in seconds.
  - **width** (integer) - The width of the video in pixels.
  - **height** (integer) - The height of the video in pixels.
  - **fps** (integer) - The frames per second of the video.
  - **s3Key** (string) - The S3 key for the video file.
  - **transcriptionStatus** (string) - The transcription status.
  - **metadata** (object) - Any associated metadata.
  - **deletedAt** (string) - The deletion timestamp, if deleted.
  - **createdAt** (string) - The creation timestamp.
  - **updatedAt** (string) - The last update timestamp.

#### Response Example
{
  "data": {
    "id": "abc123def456",
    "appId": "app_789",
    "externalUserId": "user_42",
    "name": "Product Demo",
    "duration": 124.5,
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "s3Key": "developer/app_789/abc123def456/result.mp4",
    "transcriptionStatus": "COMPLETE",
    "metadata": null,
    "deletedAt": null,
    "createdAt": "2025-06-15T10:30:00.000Z",
    "updatedAt": "2025-06-15T10:32:00.000Z"
  }
}
```

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

### Get Usage

Source: https://github.com/capsoftware/cap/blob/main/apps/web/content/docs/api/rest-api.mdx

Retrieve your app's credit balance and aggregate video statistics.

```APIDOC
## GET /api/developer/v1/usage

### Description
Retrieve your app's credit balance and aggregate video statistics.

### Method
GET

### Endpoint
/api/developer/v1/usage

### Response
#### Success Response (200)
- **data** (object) - Contains usage statistics.
  - **balanceMicroCredits** (number) - The remaining credit balance in micro-credits.
  - **balanceDollars** (string) - The remaining credit balance in dollars.
  - **totalVideos** (number) - The total number of videos processed.
  - **totalDurationMinutes** (number) - The total duration of processed videos in minutes.

### Response Example
```json
{
  "data": {
    "balanceMicroCredits": 500000,
    "balanceDollars": "5.00",
    "totalVideos": 23,
    "totalDurationMinutes": 87.5
  }
}
```
```

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

### Get Video Status

Source: https://github.com/capsoftware/cap/blob/main/apps/web/content/docs/api/rest-api.mdx

Check whether a video is fully processed and ready for playback by retrieving its status.

```APIDOC
## GET /api/developer/v1/videos/:id/status

### Description
Check whether a video is fully processed and ready for playback.

### Method
GET

### Endpoint
/api/developer/v1/videos/:id/status

### Parameters
#### Path Parameters
- **id** (string) - Required - The video ID

### Response
#### Success Response (200)
- **data** (object) - Contains video processing status details.
  - **id** (string) - The video ID.
  - **duration** (number) - The duration of the video in seconds.
  - **width** (number) - The width of the video in pixels.
  - **height** (number) - The height of the video in pixels.
  - **transcriptionStatus** (string) - The status of the video transcription. Possible values: `PROCESSING`, `COMPLETE`, `ERROR`, `SKIPPED`, `NO_AUDIO`.
  - **ready** (boolean) - Indicates if the video is fully processed and ready for playback.

### Response Example
```json
{
  "data": {
    "id": "abc123def456",
    "duration": 124.5,
    "width": 1920,
    "height": 1080,
    "transcriptionStatus": "COMPLETE",
    "ready": true
  }
}
```
```

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

### Docker Service Management

Source: https://github.com/capsoftware/cap/blob/main/AGENTS.md

Commands to manage Docker services for the project, including starting, stopping, and cleaning up containers.

```bash
pnpm docker:up
pnpm docker:stop
pnpm docker:clean
```