### TypeScript Frontend Integration Examples

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Demonstrates various frontend functionalities using TypeScript, including listing and adding videos, creating markers, generating clips, compiling videos, monitoring progress via EventSource, downloading music, detecting beats, and controlling Handy devices. These examples utilize auto-generated API client functions.

```typescript
import {
  listVideos,
  addNewVideos,
  createNewMarker,
  fetchClips,
  createVideo,
  downloadMusic,
  getBeats,
  startHandy
} from './api';

// List videos with search
const videos = await listVideos({
  page: 0,
  size: 20,
  query: 'performer name',
  hasMarkers: true,
  sort: 'created_on',
  dir: 'desc'
});

// Add videos from folder
const newVideos = await addNewVideos({
  type: 'Folder',
  path: '/home/user/videos'
});

// Create marker
const marker = await createNewMarker({
  videoId: 'abc123',
  title: 'Scene 1',
  startTime: 30.5,
  endTime: 125.8,
  indexWithinVideo: 0
});

// Generate clips with round-robin selection
const clipsResult = await fetchClips({
  markers: videos.items[0].markers,
  seed: 'reproducible-seed',
  clipOptions: {
    pickerOptions: {
      type: 'RoundRobin',
      data: {
        videosPerMarker: 3,
        clipCount: 30
      }
    },
    order: 'Random',
    lengthOptions: {
      type: 'Randomized',
      data: {
        min: 5.0,
        max: 15.0,
        overlap: 0.0
      }
    }
  }
});

// Create compilation
const compilation = await createVideo({
  videoId: 'compilation-001',
  fileName: 'My Compilation',
  clips: clipsResult.clips,
  selectedMarkers: videos.items[0].markers,
  outputResolution: [1920, 1080],
  outputFps: 60,
  songIds: [1],
  musicVolume: 0.3,
  videoCodec: 'h264',
  videoQuality: 'high',
  encodingEffort: 'medium',
  padding: 'blur',
  forceReEncode: false,
  includeOriginalFileName: true
});

// Monitor progress with EventSource
const eventSource = new EventSource(`/api/progress/${compilation.progressId}/stream`);
eventSource.onmessage = (event) => {
  const progress = JSON.parse(event.data);
  console.log(`Progress: ${progress.progress * 100}% - ${progress.message}`);
  if (progress.stage === 'Done') {
    eventSource.close();
  }
};

// Download and detect beats for music
const song = await downloadMusic({ url: 'https://example.com/song.mp3' });
const beats = await getBeats(song.id);
console.log(`Detected ${beats.offsets.length} beats`);

// Control Handy device
await startHandy({
  pattern: {
    type: 'Random',
    speedRange: { min: 20, max: 80 },
    slideRange: { min: 0, max: 100 },
    intervalRange: { min: 5, max: 15 },
    jitter: 0.2,
    seed: 'random-seed'
  }
});
```

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

### Start Handy Device - Curl

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Initiates control of a Handy device with a specified pattern. Uses POST to /api/handy/start with a JSON payload detailing the pattern type and parameters.

```bash
curl -X POST "http://localhost:5174/api/handy/start"
  -H "Content-Type: application/json"
  -d '{ "pattern": { "type": "CycleAccellerate", "cycleDuration": 30.0, "sessionDuration": 600.0, "startRange": {"min": 20, "max": 40}, "endRange": {"min": 60, "max": 80}, "slideRange": {"min": 0, "max": 100} } }'
```

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

### Handy Device Control API

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Controls the Handy interactive device, allowing users to start movement patterns synchronized to content.

```APIDOC
## POST /api/handy/start

### Description
Starts the Handy device with a specified movement pattern.

### Method
POST

### Endpoint
`/api/handy/start`

### Parameters
None

### Request Body
- **pattern** (object) - Required - Defines the movement pattern for the Handy device.
  - **type** (string) - Required - The type of pattern (e.g., "CycleAccellerate").
  - **cycleDuration** (number) - Required for "CycleAccellerate" - Duration of one cycle in seconds.
  - **sessionDuration** (number) - Required - Total duration of the Handy session in seconds.
  - **startRange** (object) - Required - Range for the start of the pattern.
    - **min** (integer) - Minimum value for the start range.
    - **max** (integer) - Maximum value for the start range.
  - **endRange** (object) - Required - Range for the end of the pattern.
    - **min** (integer) - Minimum value for the end range.
    - **max** (integer) - Maximum value for the end range.
  - **slideRange** (object) - Required - Range for sliding movements.
    - **min** (integer) - Minimum value for the slide range.
    - **max** (integer) - Maximum value for the slide range.

### Request Example
```json
{
  "pattern": {
    "type": "CycleAccellerate",
    "cycleDuration": 30.0,
    "sessionDuration": 600.0,
    "startRange": {"min": 20, "max": 40},
    "endRange": {"min": 60, "max": 80},
    "slideRange": {"min": 0, "max": 100}
  }
}
```

### Response
#### Success Response (200)
Indicates that the Handy device has started. The response structure is typically a confirmation message.
```

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

### Get Configuration - Curl

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Retrieves the current application configuration, including Stash and Handy settings. Uses GET on /api/system/configuration. Expects JSON response.

```bash
curl -X GET "http://localhost:5174/api/system/configuration"
  -H "Accept: application/json"
```

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

### Create and Manage Markers - Bash

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Creates time-based markers to define segments within videos. Markers specify start and end times with optional titles for categorization. Includes examples for creating, updating, and splitting markers using curl.

```bash
# Create a new marker
curl -X POST "http://localhost:5174/api/library/marker" \
  -H "Content-Type: application/json" \
  -d '{
    "videoId": "abc123",
    "title": "Action Scene",
    "startTime": 30.5,
    "endTime": 125.8,
    "indexWithinVideo": 0
  }'

# Update existing marker
curl -X PUT "http://localhost:5174/api/library/marker/42" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Scene",
    "startTime": 31.0,
    "endTime": 126.0
  }'

# Split marker at specific timestamp
curl -X POST "http://localhost:5174/api/library/marker/42/split?time=78.5" \
  -H "Accept: application/json"
```

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

### Build ClipMash for Development (Rust/Node.js)

Source: https://github.com/soundchaser128/clip-mash/blob/main/README.md

These commands outline the steps to build ClipMash for development. It involves installing SQLx CLI for database migrations, setting up the frontend with npm, and then running the main Rust application.

```shell
# Required to create the database and apply the schema
sqlx install sqlx-cli
sqlx migrate run

cd frontend
npm install
npm run dev

# In a new shell, in the project root:
cargo run
```

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

### Build ClipMash for Production (Rust/Node.js)

Source: https://github.com/soundchaser128/clip-mash/blob/main/README.md

These commands detail the process for building ClipMash for production. It includes installing frontend dependencies, building the frontend for production, setting up the database schema, and finally compiling the Rust application in release mode.

```shell
cd frontend
npm install
npm run build

cd ..
# Required to create the database and apply the schema
sqlx install sqlx-cli
sqlx migrate run
cargo build --release
```

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

### Start Random Playback Pattern

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Initiates playback with a random pattern, allowing configuration of speed, slide, and interval ranges, along with jitter and a seed for reproducibility.

```bash
curl -X POST "http://localhost:5174/api/handy/start" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": {
      "type": "Random",
      "speedRange": {"min": 20, "max": 80},
      "slideRange": {"min": 0, "max": 100},
      "intervalRange": {"min": 5, "max": 15},
      "jitter": 0.2,
      "seed": "random-seed"
    }
  }'
```

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

### Get Application Version using cURL

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Retrieves the current version and build date of the application. It sends a GET request to the /api/system/version endpoint and expects a JSON response.

```shell
curl -X GET "http://localhost:5174/api/system/version" \
  -H "Accept: application/json"
```

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

### Get Video Details with Markers

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Retrieves comprehensive details for a specific video, including its metadata, markers, tags, and ffprobe information. Requires a video ID in the URL.

```bash
curl -X GET "http://localhost:5174/api/library/video/abc123" \
  -H "Accept: application/json"
```

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

### Generate Combined Funscript - Curl

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Generates a combined funscript from existing funscripts linked to video markers. Requires a JSON payload specifying video clips, marker IDs, start, and end times. POST to /api/project/funscript/combined.

```bash
curl -X POST "http://localhost:5174/api/project/funscript/combined"
  -H "Content-Type: application/json"
  -d '{ "clips": [ { "videoId": "abc123", "markerId": 42, "startTime": 12.5, "endTime": 23.8 } ] }'
```

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

### Rust: Generate Preview Images

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

This snippet shows how to generate preview images for a video at a specified timestamp. It initializes the `PreviewGenerator` with directory and ffmpeg information, then calls the `generate_preview` method. Dependencies include `clipmash::service::preview_image`.

```rust
use clipmash::service::preview_image::PreviewGenerator;
use std::sync::Arc;

// Assuming 'state' is an Arc<AppState> with directories and ffmpeg_location
let preview_gen = PreviewGenerator::new(
    state.directories.clone(),
    state.ffmpeg_location.clone(),
);
let preview_path = preview_gen.generate_preview(
    "video-id",
    "/path/to/video.mp4",
    30.0  // timestamp in seconds
).await?;
```

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

### Playback Control API

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Control the playback of audio or video clips, including starting with custom patterns, checking status, pausing, and stopping.

```APIDOC
## POST /api/handy/start

### Description
Starts playback with a specified random pattern configuration.

### Method
POST

### Endpoint
/api/handy/start

### Parameters
#### Request Body
- **pattern** (object) - Required - Configuration for the playback pattern.
  - **type** (string) - Required - Type of pattern, e.g., "Random".
  - **speedRange** (object) - Required - Range for playback speed.
    - **min** (number) - Required - Minimum speed.
    - **max** (number) - Required - Maximum speed.
  - **slideRange** (object) - Required - Range for slide effect.
    - **min** (number) - Required - Minimum slide value.
    - **max** (number) - Required - Maximum slide value.
  - **intervalRange** (object) - Required - Range for playback interval.
    - **min** (number) - Required - Minimum interval.
    - **max** (number) - Required - Maximum interval.
  - **jitter** (number) - Optional - Jitter value for randomness.
  - **seed** (string) - Optional - Seed for random number generation.

### Request Example
```json
{
  "pattern": {
    "type": "Random",
    "speedRange": {"min": 20, "max": 80},
    "slideRange": {"min": 0, "max": 100},
    "intervalRange": {"min": 5, "max": 15},
    "jitter": 0.2,
    "seed": "random-seed"
  }
}
```

## GET /api/handy

### Description
Retrieves the current status of the playback.

### Method
GET

### Endpoint
/api/handy

### Response
#### Success Response (200)
- **currentVelocity** (number) - The current playback velocity.
- **elapsed** (number) - The elapsed playback time in seconds.
- **paused** (boolean) - Indicates if playback is currently paused.

#### Response Example
```json
{
  "currentVelocity": 45,
  "elapsed": 123.5,
  "paused": false
}
```

## POST /api/handy/pause

### Description
Pauses the current playback.

### Method
POST

### Endpoint
/api/handy/pause

## POST /api/handy/stop

### Description
Stops the current playback.

### Method
POST

### Endpoint
/api/handy/stop
```

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

### Rust: Integrate with Stash API

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

This snippet shows how to interact with the Stash API for finding scenes and adding markers. It includes setting up the `StashApi` with configuration and demonstrates methods for searching scenes with pagination and markers, and adding a marker to a scene. Requires `clipmash::data::stash_api::StashApi` and related types.

```rust
use clipmash::data::stash_api::{StashApi, StashConfig, PageParameters};

let stash_api = StashApi::with_config(StashConfig {
    stash_url: "http://localhost:9999".to_string(),
    api_key: Some("api-key".to_string()),
});

// Find scenes
let (scenes, total) = stash_api.find_scenes(
    &PageParameters { page: 0, size: 20 },
    Some("query".to_string()),
    Some(true)  // with_markers
).await?;

// Add marker to Stash scene
// Assuming 'marker' is a Marker object and 'scene-id' is a valid scene ID
let stash_marker_id = stash_api.add_marker(marker, "scene-id".to_string()).await?;
```

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

### Get All Tags with Counts

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Retrieves a list of all available tags used in the library, along with their respective counts. This is useful for filtering and understanding tag distribution.

```bash
curl -X GET "http://localhost:5174/api/library/video/tags" \
  -H "Accept: application/json"
```

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

### Configuration Management API

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Manages application settings, including configurations for Stash integration and Handy device control.

```APIDOC
## GET /api/system/configuration

### Description
Retrieves the current application configuration.

### Method
GET

### Endpoint
`/api/system/configuration`

### Parameters
None

### Request Body
None

### Response
#### Success Response (200)
- **stash** (object) - Stash integration settings.
  - **stashUrl** (string) - The URL of the Stash server.
  - **apiKey** (string) - The API key for Stash authentication.
- **handy** (object) - Handy device settings.
  - **key** (string) - The connection key for the Handy device.
  - **enabled** (boolean) - Whether the Handy integration is enabled.

#### Response Example
```json
{
  "stash": {
    "stashUrl": "http://localhost:9999",
    "apiKey": "your-api-key"
  },
  "handy": {
    "key": "your-handy-connection-key",
    "enabled": true
  }
}
```
```

```APIDOC
## POST /api/system/configuration

### Description
Updates the application configuration.

### Method
POST

### Endpoint
`/api/system/configuration`

### Parameters
None

### Request Body
- **stash** (object) - Stash integration settings to update.
  - **stashUrl** (string) - The URL of the Stash server.
  - **apiKey** (string) - The API key for Stash authentication.
- **handy** (object) - Handy device settings to update.
  - **key** (string) - The connection key for the Handy device.
  - **enabled** (boolean) - Whether the Handy integration is enabled.

### Request Example
```json
{
  "stash": {
    "stashUrl": "http://localhost:9999",
    "apiKey": "new-api-key"
  },
  "handy": {
    "key": "new-connection-key",
    "enabled": true
  }
}
```

### Response
#### Success Response (200)
Indicates successful update. The response structure is typically a confirmation or the updated configuration itself.
```

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

### Add Videos to Library - Bash

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Adds new videos to the library from local paths, download URLs, or Stash scene IDs. Automatically extracts metadata using ffprobe and generates preview images. Demonstrates adding videos from different sources using curl.

```bash
# Add videos from local folder
curl -X POST "http://localhost:5174/api/library/video" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Folder",
    "path": "/home/user/videos"
  }'

# Add videos by downloading from URLs
curl -X POST "http://localhost:5174/api/library/video" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Download",
    "urls": [
      "https://example.com/video1.mp4",
      "https://example.com/video2.mp4"
    ]
  }'

# Add videos from Stash
curl -X POST "http://localhost:5174/api/library/video" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Stash",
    "sceneIds": [12345, 67890]
  }'
```

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

### Health Check using cURL

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Performs a health check on the application by sending a GET request to the /api/system/health endpoint. A successful response is indicated by a 200 OK status.

```shell
curl -X GET "http://localhost:5174/api/system/health" \
  -H "Accept: application/json"
```

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

### POST /api/project/create - Create Video Compilation

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Compiles clips into a final video with specified encoding settings, resolution, and optional music overlay. This is an asynchronous operation with progress tracking.

```APIDOC
## POST /api/project/create

### Description
Compiles clips into a final video with specified encoding settings, resolution, and optional music overlay. This is an asynchronous operation with progress tracking.

### Method
POST

### Endpoint
/api/project/create

### Parameters
#### Request Body
- **videoId** (string) - Required - A unique identifier for the compilation.
- **fileName** (string) - Required - The desired name for the output video file.
- **clips** (array) - Required - An array of clip objects to include in the compilation.
  - **videoId** (string) - Required - The ID of the video the clip originates from.
  - **markerId** (integer) - Required - The ID of the marker associated with the clip.
  - **startTime** (number) - Required - The start time of the clip in seconds.
  - **endTime** (number) - Required - The end time of the clip in seconds.
- **selectedMarkers** (array) - Required - An array of marker objects used for selection.
- **outputResolution** (array) - Required - An array of two integers representing [width, height] (e.g., [1920, 1080]).
- **outputFps** (integer) - Required - The frames per second for the output video.
- **songIds** (array) - Optional - An array of song IDs to overlay.
- **musicVolume** (number) - Optional - The volume of the overlay music (0.0 to 1.0).
- **videoCodec** (string) - Optional - The video codec to use (e.g., "h264"). Defaults to "h264".
- **videoQuality** (string) - Optional - The quality setting for the video (e.g., "high", "medium", "low"). Defaults to "high".
- **encodingEffort** (string) - Optional - The encoding effort level (e.g., "fast", "medium", "slow"). Defaults to "medium".
- **padding** (string) - Optional - The padding method for aspect ratio differences (e.g., "blur", "black"). Defaults to "blur".
- **forceReEncode** (boolean) - Optional - Whether to force re-encoding even if source is compatible. Defaults to false.
- **includeOriginalFileName** (boolean) - Optional - Whether to include the original file name in metadata. Defaults to true.

### Request Example
```json
{
  "videoId": "compilation-001",
  "fileName": "My Compilation",
  "clips": [
    {
      "videoId": "abc123",
      "markerId": 42,
      "startTime": 12.5,
      "endTime": 23.8
    }
  ],
  "selectedMarkers": [
    {"id": 42, "videoId": "abc123", "title": "Scene 1", "startTime": 0, "endTime": 100}
  ],
  "outputResolution": [1920, 1080],
  "outputFps": 60,
  "songIds": [1],
  "musicVolume": 0.3,
  "videoCodec": "h264",
  "videoQuality": "high",
  "encodingEffort": "medium",
  "padding": "blur",
  "forceReEncode": false,
  "includeOriginalFileName": true
}
```

### Response
#### Success Response (200)
- **progressId** (string) - The ID to use for tracking compilation progress.
- **progressUrl** (string) - The URL to stream progress updates via Server-Sent Events.

#### Response Example
```json
{
  "progressId": "compilation-001",
  "progressUrl": "/api/progress/compilation-001/stream"
}
```

### Progress Monitoring
#### GET /api/progress/{progressId}/stream

### Description
Monitors the progress of an asynchronous compilation job.

### Method
GET

### Endpoint
/api/progress/{progressId}/stream

### Parameters
#### Path Parameters
- **progressId** (string) - Required - The ID of the compilation job.

### Request Example
```bash
curl -X GET "http://localhost:5174/api/progress/compilation-001/stream" \
  -H "Accept: text/event-stream"
```

### Response
#### Success Response (200)
Server-Sent Events stream with progress updates.

#### Response Example
```
data: {"stage":"Gathering","progress":0.0,"message":"Starting compilation"}
...
data: {"stage":"Done","progress":1.0,"message":"Compilation complete"}
```

### Video Download
#### GET /api/project/download

### Description
Downloads the completed video compilation.

### Method
GET

### Endpoint
/api/project/download

### Parameters
#### Query Parameters
- **videoId** (string) - Required - The ID of the compilation video to download.

### Request Example
```bash
curl -X GET "http://localhost:5174/api/project/download?videoId=compilation-001" \
  --output compilation.mp4
```
```

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

### Get Marker Titles with Counts (Autocomplete)

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Retrieves marker titles that match a given prefix, along with their counts. This endpoint is designed for autocomplete functionality in user interfaces.

```bash
curl -X GET "http://localhost:5174/api/library/marker/title?prefix=Sce&count=10" \
  -H "Accept: application/json"
```

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

### File System Browser API

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Allows browsing the local file system to select video source directories. Provides details about directory contents.

```APIDOC
## GET /api/library/directory

### Description
Lists the contents of a specified directory in the local file system.

### Method
GET

### Endpoint
/api/library/directory

### Parameters
#### Query Parameters
- **path** (string) - Required - The absolute path of the directory to list.
- **includeHidden** (boolean) - Optional - Whether to include hidden files and directories. Defaults to false.

### Response
#### Success Response (200)
- **path** (string) - The path of the directory that was listed.
- **entries** (array of objects) - An array of file system entries within the directory.
  - **name** (string) - The name of the file or directory.
  - **path** (string) - The full path to the file or directory.
  - **isDirectory** (boolean) - True if the entry is a directory, false otherwise.
  - **size** (number) - The size of the file in bytes (if applicable).

#### Response Example
```json
{
  "path": "/home/user/videos",
  "entries": [
    {
      "name": "video1.mp4",
      "path": "/home/user/videos/video1.mp4",
      "isDirectory": false,
      "size": 1048576000
    },
    {
      "name": "subfolder",
      "path": "/home/user/videos/subfolder",
      "isDirectory": true
    }
  ]
}
```
```

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

### Get Current Progress Snapshot

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Retrieves a snapshot of the current progress for a long-running operation. This provides the current stage, progress percentage, a status message, and clip information.

```bash
curl -X GET "http://localhost:5174/api/progress/compilation-001/info" \
  -H "Accept: application/json"
```

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

### Music Management and Beat Detection API

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Endpoints for uploading, downloading, and detecting beats in music tracks.

```APIDOC
## Music Management and Beat Detection

### Description
Provides endpoints for managing music tracks, including uploading, downloading, and automatically detecting beats for synchronization purposes.

### Endpoints
(Specific endpoints for music management and beat detection are not detailed in the provided text, but would typically include operations like:
- POST /api/music/upload
- GET /api/music/{id}
- GET /api/music/{id}/download
- POST /api/music/{id}/detect-beats)
```

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

### Get Current Playback Status

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Retrieves the current playback status, including velocity, elapsed time, and pause state. The response provides a snapshot of the ongoing playback.

```bash
curl -X GET "http://localhost:5174/api/handy" \
  -H "Accept: application/json"
```

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

### Rust: Create Combined Funscript

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

This code demonstrates the creation of a combined funscript from a list of clips. It utilizes the `ScriptBuilder` and requires access to the application's database. The `create_combined_funscript` method takes the clips as input.

```rust
use clipmash::service::funscript::ScriptBuilder;
use std::sync::Arc;

// Assuming 'state' is an Arc<AppState> with database
// Assuming 'clips_result' is the result from clip generation
let script_builder = ScriptBuilder::new(state.database.clone());
let funscript = script_builder.create_combined_funscript(clips_result.clips).await?;
```

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

### Rust: Compile Video Clips

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

This code snippet shows how to set up and use the `CompilationGenerator` to compile video clips into a final output. It defines compilation options such as video ID, output resolution, FPS, file name, song information, and encoding settings. It requires access to database, directories, and ffmpeg location.

```rust
use clipmash::service::generator::{CompilationGenerator, CompilationOptions};
use clipmash::service::video_codec::VideoCodec;
use clipmash::service::video_quality::VideoQuality;
use clipmash::service::encoding_effort::EncodingEffort;
use clipmash::service::padding_type::PaddingType;
use std::sync::Arc;

// Assuming 'state' is an Arc<AppState> with database, directories, and ffmpeg_location
// Assuming 'clips_result' is the result from clip generation
let generator = CompilationGenerator::new(
    state.database.clone(),
    state.directories.clone(),
    state.ffmpeg_location.clone(),
);

let options = CompilationOptions {
    video_id: "compilation-001".to_string(),
    clips: clips_result.clips.clone(), // Use cloned clips if needed elsewhere
    markers: vec![/* markers */],
    output_resolution: (1920, 1080),
    output_fps: 60,
    file_name: "My Compilation".to_string(),
    songs: vec![/* songs */],
    music_volume: 0.3,
    video_codec: VideoCodec::H264,
    video_quality: VideoQuality::High,
    encoding_effort: EncodingEffort::Medium,
    videos: vec![/* videos */],
    padding: PaddingType::Blur,
    force_re_encode: false,
    include_original_file_name: true,
};

generator.compile_clips(&options, clips_result.clips).await?;
```

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

### List Stash Videos - Curl

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Retrieves a list of videos from Stash with optional filtering and marker inclusion. Uses GET on /api/library/video/stash with pagination and query parameters. Returns JSON.

```bash
curl -X GET "http://localhost:5174/api/library/video/stash?page=0&size=20&query=performer&withMarkers=true"
  -H "Accept: application/json"
```

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

### Get Storage Statistics

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Retrieves statistics on storage usage for different categories of files within the library. The response is an array of arrays, where each inner array contains the category name and its size in bytes.

```bash
curl -X GET "http://localhost:5174/api/library/stats" \
  -H "Accept: application/json"
```

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

### Rust: Generate Clips from Markers

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

This snippet demonstrates how to initialize the clip service and generate video clips from a list of markers. It includes options for seed, clip count, order, and length randomization. Dependencies include the `clipmash::service::clip` module.

```rust
use clipmash::service::clip::{ClipService, CreateClipsOptions, ClipOptions};
use clipmash::service::clip::clip_picker_options::{ClipPickerOptions, RoundRobinClipOptions};
use clipmash::service::clip::clip_length_options::{ClipLengthOptions, RandomizedClipOptions};
use clipmash::service::clip::clip_order::ClipOrder;

// Assuming 'markers' is a Vec<Marker> and other necessary types are defined
let clip_service = ClipService::new();
let clips_result = clip_service.arrange_clips(CreateClipsOptions {
    markers: vec![/* markers */],
    seed: Some("reproducible-seed".to_string()),
    clip_options: ClipOptions {
        picker_options: ClipPickerOptions::RoundRobin(RoundRobinClipOptions {
            videos_per_marker: 3,
            clip_count: 30,
        }),
        order: ClipOrder::Random,
        length_options: ClipLengthOptions::Randomized(RandomizedClipOptions {
            min: 5.0,
            max: 15.0,
            overlap: 0.0,
        }),
    },
});
```

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

### Test Stash Connection - Curl

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Tests the connection to a Stash server by sending a GET request to /api/stash/health. Requires Stash URL and API key as query parameters. Expects a simple text response.

```bash
curl -X GET "http://localhost:5174/api/stash/health?url=http://localhost:9999&apiKey=your-api-key"
  -H "Accept: application/json"
```

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

### Generate Clips with Music Beat Synchronization (Bash)

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Generates video clips synchronized to music beats, enabling rhythm-matched compilations. This API call specifies markers, a seed for consistency, and clip length options tied to song beats and their offsets.

```bash
# Generate clips aligned to song beats
curl -X POST "http://localhost:5174/api/project/clips" \
  -H "Content-Type: application/json" \
  -d '{
    "markers": [
      {"id": 42, "videoId": "abc123", "title": "Scene 1", "startTime": 0, "endTime": 100}
    ],
    "seed": "beat-sync",
    "clipOptions": {
      "pickerOptions": {
        "type": "RoundRobin",
        "data": {
          "videosPerMarker": 2,
          "clipCount": 50
        }
      },
      "order": "Random",
      "lengthOptions": {
        "type": "Songs",
        "data": {
          "songs": [
            {
              "id": 1,
              "duration": 240.5,
              "beats": {
                "offsets": [0.5, 1.0, 1.5, 2.0, 2.5],
                "length": 240.5
              }
            }
          ],
          "beatsPerClip": 4
        }
      }
    }
  }'
```

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

### Create Video Compilation (Bash)

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Initiates the creation of a video compilation from specified clips and markers. This API call supports various encoding settings, resolution, frame rate, and optional music overlay. It returns a progress ID to monitor the asynchronous compilation process.

```bash
# Create compilation with H.264 encoding
curl -X POST "http://localhost:5174/api/project/create" \
  -H "Content-Type: application/json" \
  -d '{
    "videoId": "compilation-001",
    "fileName": "My Compilation",
    "clips": [
      {
        "videoId": "abc123",
        "markerId": 42,
        "startTime": 12.5,
        "endTime": 23.8
      }
    ],
    "selectedMarkers": [
      {"id": 42, "videoId": "abc123", "title": "Scene 1", "startTime": 0, "endTime": 100}
    ],
    "outputResolution": [1920, 1080],
    "outputFps": 60,
    "songIds": [1],
    "musicVolume": 0.3,
    "videoCodec": "h264",
    "videoQuality": "high",
    "encodingEffort": "medium",
    "padding": "blur",
    "forceReEncode": false,
    "includeOriginalFileName": true
  }'
```

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

### Retrieve Song Beats - Curl

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Retrieves beat information for a specific song identified by its ID. Uses a GET request to /api/song/{id}/beats. Expects JSON response containing beat offsets and song length.

```bash
curl -X GET "http://localhost:5174/api/song/1/beats"
  -H "Accept: application/json"
```

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

### List Videos with Pagination and Search - Bash

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Retrieves a paginated list of videos from the library with optional filtering by search query, marker presence, interactive status, and sorting options. Supports full-text search on video titles, tags, and file paths. Uses curl for making HTTP requests.

```bash
# Search videos with markers, sorted by creation date
curl -X GET "http://localhost:5174/api/library/video?page=0&size=20&query=performer+name&hasMarkers=true&sort=created_on&dir=desc" \
  -H "Accept: application/json"
```

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

### Restart Application using cURL

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Initiates a restart of the application by sending a POST request to the /api/system/restart endpoint.

```shell
curl -X POST "http://localhost:5174/api/system/restart"
```

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

### Add Videos to Library

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Adds new videos to the library from local paths, download URLs, or Stash scene IDs. Automatically extracts metadata using ffprobe and generates preview images.

```APIDOC
## POST /api/library/video

### Description
Adds new videos to the library from local paths, download URLs, or Stash scene IDs. Automatically extracts metadata using ffprobe and generates preview images.

### Method
POST

### Endpoint
/api/library/video

#### Request Body
- **type** (string) - Required - The type of video source ('Folder', 'Download', 'Stash').
- **path** (string) - Optional (required if type is 'Folder') - The local file system path to the video or folder.
- **urls** (array of strings) - Optional (required if type is 'Download') - A list of URLs to download videos from.
- **sceneIds** (array of integers) - Optional (required if type is 'Stash') - A list of Stash scene IDs.

### Request Example
```json
// Add videos from local folder
{
  "type": "Folder",
  "path": "/home/user/videos"
}

// Add videos by downloading from URLs
{
  "type": "Download",
  "urls": [
    "https://example.com/video1.mp4",
    "https://example.com/video2.mp4"
  ]
}

// Add videos from Stash
{
  "type": "Stash",
  "sceneIds": [
    12345,
    67890
  ]
}
```

### Response
#### Success Response (200)
- Returns an array of newly added video objects.
  - **id** (string) - Unique identifier for the video.
  - **title** (string) - The title of the video.
  - **filePath** (string) - The path to the video file.
  - **duration** (float) - The duration of the video in seconds.
  - **interactive** (boolean) - Indicates if the video is interactive.
  - **source** (string) - The source of the video.
  - **previewImage** (string) - URL to the video's preview image.

#### Response Example
```json
[
  {
    "id": "xyz789",
    "title": "Video Title",
    "filePath": "/app/data/downloads/video1.mp4",
    "duration": 897.3,
    "interactive": true,
    "source": "Download",
    "previewImage": "/api/library/video/xyz789/preview"
  }
]
```
```

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

### POST /api/project/clips - Generate Clips with Music Beat Synchronization

Source: https://context7.com/soundchaser128/clip-mash/llms.txt

Generates clips synchronized to music beats for rhythm-matched video compilations.

```APIDOC
## POST /api/project/clips (Music Beat Synchronization)

### Description
Generates clips synchronized to music beats for rhythm-matched video compilations.

### Method
POST

### Endpoint
/api/project/clips

### Parameters
#### Request Body
- **markers** (array) - Required - An array of marker objects.
- **seed** (string) - Optional - A seed for reproducible random generation.
- **clipOptions** (object) - Required - Options for clip generation.
  - **pickerOptions** (object) - Required - Options for selecting clips.
    - **type** (string) - Required - The type of picker (e.g., "RoundRobin").
    - **data** (object) - Required - Specific data for the picker type.
      - **videosPerMarker** (integer) - Required - Number of videos to pick per marker.
      - **clipCount** (integer) - Required - Total number of clips to generate.
  - **order** (string) - Required - The order of clips (e.g., "Random").
  - **lengthOptions** (object) - Required - Options for clip length.
    - **type** (string) - Required - Set to "Songs" for beat synchronization.
    - **data** (object) - Required - Specific data for the "Songs" length type.
      - **songs** (array) - Required - Array of song objects.
        - **id** (integer) - Required - Song ID.
        - **duration** (number) - Required - Song duration.
        - **beats** (object) - Required - Beat information.
          - **offsets** (array) - Required - Array of beat start times.
          - **length** (number) - Required - Total length of the beats sequence.
      - **beatsPerClip** (integer) - Required - Number of beats per clip.

### Request Example
```json
{
  "markers": [
    {"id": 42, "videoId": "abc123", "title": "Scene 1", "startTime": 0, "endTime": 100}
  ],
  "seed": "beat-sync",
  "clipOptions": {
    "pickerOptions": {
      "type": "RoundRobin",
      "data": {
        "videosPerMarker": 2,
        "clipCount": 50
      }
    },
    "order": "Random",
    "lengthOptions": {
      "type": "Songs",
      "data": {
        "songs": [
          {
            "id": 1,
            "duration": 240.5,
            "beats": {
              "offsets": [0.5, 1.0, 1.5, 2.0, 2.5],
              "length": 240.5
            }
          }
        ],
        "beatsPerClip": 4
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **clips** (array) - An array of generated clip objects.
- **totalDuration** (number) - The total duration of all generated clips.
- **beatOffsets** (array) - An array of beat offsets for synchronization.

#### Response Example
```json
{
  "clips": [...],
  "totalDuration": 240.5,
  "beatOffsets": [0.5, 1.0, 1.5, 2.0, 2.5, 3.0]
}
```
```