<!-- module: process -->
<!-- description: Processing pipeline — trigger, probe, progress, jobs -->
<!-- depends: 01_auth, 03_register -->

## Processing Pipeline

### `POST /api/v1/file/:file_uuid/process`

**Auth**: Required
**Scope**: file-level

Trigger the processing pipeline for a registered file. Creates a monitor job that the worker picks up and processes sequentially. Returns immediately with the job info—processing runs asynchronously in the background.

#### Request Parameters

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `processors` | string[] | No | all | Specific processors to run: `["cut","asr","asrx","yolo","ocr","face","pose","visual_chunk","story","5w1h"]` |
| `rules` | string[] | No | all | Rule names to apply (currently unused) |

#### Example

```bash
# Run all processors
curl -s -X POST "$API/api/v1/file/$FILE_UUID/process" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" -d '{}'

# Run specific processors only
curl -s -X POST "$API/api/v1/file/$FILE_UUID/process" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"processors": ["asr", "face", "yolo"]}'
```

#### Response (200)

```json
{
  "success": true,
  "job_id": 42,
  "file_uuid": "3a6c1865...",
  "status": "processing",
  "pids": [12345, 12346],
  "message": "Processing triggered for video.mp4"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Always true on 200 |
| `job_id` | integer | Monitor job ID (for job tracking) |
| `file_uuid` | string | 32-char hex UUID of the file |
| `status` | string | `"processing"` |
| `pids` | integer[] | Process IDs of started processors |
| `message` | string | Human-readable status |

#### Error Responses

| HTTP | When |
|------|------|
| `404` | File UUID not found |
| `401` | Missing or invalid API key |

---

### `GET /api/v1/file/:file_uuid/probe`

**Auth**: Required
**Scope**: file-level

Get ffprobe metadata for a registered file. Returns video/audio stream info, codec details, duration, resolution, and frame rate.

#### Example

```bash
curl -s "$API/api/v1/file/$FILE_UUID/probe" -H "X-API-Key: $KEY"
```

#### Response (200)

```json
{
  "file_uuid": "3a6c1865...",
  "file_name": "video.mp4",
  "file_size": 794863677,
  "duration": 120.5,
  "width": 1920,
  "height": 1080,
  "fps": 24.0,
  "total_frames": 2892,
  "cached": true,
  "format": {
    "filename": "/path/to/video.mp4",
    "format_name": "mov,mp4,m4a,3gp",
    "duration": "120.5",
    "size": "12345678",
    "bit_rate": "819200"
  },
  "streams": [
    {
      "index": 0,
      "codec_name": "h264",
      "codec_type": "video",
      "width": 1920,
      "height": 1080,
      "r_frame_rate": "24/1",
      "duration": "120.5"
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `file_uuid` | string | 32-char hex UUID |
| `file_name` | string | File name |
| `file_size` | integer | File size in bytes (from filesystem) |
| `duration` | float | Duration in seconds |
| `width` | integer | Video width in pixels |
| `height` | integer | Video height in pixels |
| `fps` | float | Frames per second |
| `total_frames` | integer | Estimated total frames |
| `cached` | boolean | True if result was from cached probe JSON |
| `format` | object | Container format info (ffprobe format section) |
| `streams` | array | Array of stream info objects |

---

### `GET /api/v1/progress/:file_uuid`

**Auth**: Required
**Scope**: file-level

Get real-time processing progress for a file via Redis pub/sub. Includes per-processor status, current/total frames, ETA, and system resource stats.

#### Pipeline Order

| Order | Processor | Dependencies | Description |
|-------|-----------|-------------|-------------|
| 1 | `cut` | — | Scene detection |
| 2 | `asr` | cut | Speech-to-text (per scene) |
| 3 | `asrx` | asr | Speaker diarization |
| 4 | `yolo` | — | Object detection |
| 5 | `ocr` | — | Text recognition |
| 6 | `face` | — | Face detection & embedding |
| 7 | `pose` | — | Pose estimation |
| 8 | `visual_chunk` | yolo | Visual scene chunks |
| 9 | `story` | asr, asrx, cut, yolo, face | Scene summaries (template) |
| 10 | `5w1h` | story | 5W1H analysis (Gemma4 LLM) |

All processors except `story` and `5w1h` run concurrently when their dependencies are met. Story and 5W1H run sequentially after their prerequisites.

#### Example

```bash
curl -s "$API/api/v1/progress/$FILE_UUID" -H "X-API-Key: $KEY" | jq '{overall_progress, processors: [.processors[] | {processor_type, status}]}'
```

#### Response (200)

```json
{
  "file_uuid": "3a6c1865...",
  "overall_progress": 71,
  "cpu_percent": 45.2,
  "gpu_percent": 30.1,
  "memory_percent": 62.4,
  "processors": [
    {"processor_type": "asr", "status": "complete", "progress": 100},
    {"processor_type": "yolo", "status": "running", "progress": 65},
    {"processor_type": "face", "status": "pending", "progress": 0}
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `file_uuid` | string | 32-char hex UUID |
| `overall_progress` | integer | Overall progress percentage (0–100) |
| `processors` | array | Per-processor status list |
| `processors[].processor_type` | string | Processor name (`asr`, `cut`, `yolo`, etc.) |
| `processors[].status` | string | `"pending"`, `"running"`, `"complete"`, or `"failed"` |
| `processors[].progress` | integer | Per-processor progress (0–100) |
| `processors[].eta_seconds` | integer | Estimated seconds remaining (running processors) |
| `processors[].current` | integer | Current frame count |
| `processors[].total` | integer | Total frame count |
| `cpu_percent` | float | Current CPU usage |
| `gpu_percent` | float | Current GPU utilization |
| `memory_percent` | float | Current memory usage |

---

### `GET /api/v1/jobs`

**Auth**: Required
**Scope**: system-level

List all processing jobs (monitor jobs) in the system. Shows job status, which file each job is processing, and current processor info.

#### Example

```bash
curl -s "$API/api/v1/jobs" -H "X-API-Key: $KEY" | jq '{count, jobs: [.jobs[] | {uuid, status}]}'
```

#### Response (200)

```json
{
  "jobs": [
    {
      "id": 42,
      "uuid": "3a6c1865...",
      "status": "running",
      "current_processor": "yolo",
      "created_at": "2026-05-16T12:00:00Z",
      "started_at": "2026-05-16T12:01:00Z"
    }
  ],
  "count": 15,
  "page": 1,
  "page_size": 20
}
```

| Field | Type | Description |
|-------|------|-------------|
| `jobs` | array | Array of job info objects |
| `jobs[].id` | integer | Job ID |
| `jobs[].uuid` | string | File UUID being processed |
| `jobs[].status` | string | `"pending"`, `"running"`, `"completed"`, `"failed"` |
| `jobs[].current_processor` | string | Currently active processor, or null |
| `count` | integer | Total job count |
| `page` | integer | Current page number |
| `page_size` | integer | Jobs per page |