add-analysis-pass

Files (1)

• SKILL.md

SKILL.md (first lines)

# Adding a New Analysis Pass

The analysis pipeline lives in `src-tauri/src/analysis/` and offers **two pass shapes**. Pick the right one before writing any code:

| Trait | When to use |
|-------|-------------|
| **`AnalysisPass`** | Per-track compute dominates (inference, DSP, API calls). The orchestrator drives the job loop, progress events, pause/resume, and metrics automatically. |
| **`BatchAnalysisPass`** | Either (a) the algorithm requires all data at once (clustering, nearest-neighbour indexing), or (b) the pass is I/O-bound and per-track SQLite round-trips are the bottleneck. You own the read-compute-write loop; the orchestrator calls `execute()` once. |

---

## Current pass priorities

> **Important:** Priorities do **not** determine the pipeline execution order. The execution order is the explicit call sequence in `PipelineManager::run()` in `analysis/mod.rs`. Priorities only control backfill ordering and the `reset_pass` tooling.

| Pass | Priority | Trait | File |
|------|----------|-------|------|
| `audio_analysis` | 10 | `AnalysisPass` | `analysis/audio.rs` |
| `sax` | 12 | `BatchAnalysisPass` | `analysis/sax.rs` |
| `sax_alignment` | 13 | `AnalysisPass` | `analysis/sax_alignment.rs` |
| `boundary_refine` | 14 | `AnalysisPass` | `analysis/boundary_refine.rs` |
| `bpm_correction` | 15 | `AnalysisPass` | `analysis/bpm_correction.rs` |
| `clap` | 20 | `AnalysisPass` | `analysis/clap.rs` |
| `essentia` | 30 | `AnalysisPass` | `analysis/essentia.rs` |
| `qwen` | 50 | `AnalysisPass` | `analysis/qwen.rs` |
| `bpm_refinement` | 55 | `AnalysisPass` | `analysis/bpm_refinement.rs` |
| `structure_cluster` | 55 | `BatchAnalysisPass` | `analysis/structure_cluster.rs` |
| `description_embed` | 60 | `AnalysisPass` | `analysis/description_embed.rs` |

Pick a priority that places your pass at the correct logical point relative to its dependencies. After choosing a priority, **also** add your pass call at the right place in `PipelineManager::run()` — that is what actually sets execution order.

---

## Adding a per-track pass (`AnalysisPass`)

### 1. DB Migration

Add columns to the `tracks` table or create new secondary tables in a new migration file:
```
src-tauri/migrations/NN_your_pass.sql
```
Register it in `src-tauri/src/database.rs`:
```rust
M::up(include_str!("../migrations/NN_your_pass.sql")),
```

### 2. Create the Pass Submodule

Create a new file `src-tauri/src/analysis/your_pass.rs`. 

1. Define a struct for your pass jobs and implement the `PassJob` trait:
```rust
pub struct YourJob {
    pub pass_id: i64,
    pub track_id: i64,
    // Add other fields you need spooled upfront
}

impl super::PassJob for YourJob {
    fn pass_id(&self) -> i64 { self.pass_id }
    fn track_id(&self) -> i64 { self.track_id }
}
```

2. Define a struct for your pass and implement the `AnalysisPass` trait:
```rust
use crate::database::pass_status;
use crate::scanner::sidecar::pass_version;
use rusqlite::Connection;

pub struct YourPass;

impl super::AnalysisPass for YourPass {
    type Job = YourJob;
    type Output = YourResultType;

    fn name(&self) -> &'static str {
        "your_pass_name"
    }

    fn priority(&self) -> i32 {
        60 // Select appropriate priority
    }

    fn version(&self) -> u32 {
        pass_version::YOUR_PASS // Add constant in scanner/sidecar.rs
    }

    fn dependencies(&self) -> &'static [&'static str] {
        &["clap"] // Declare upstream dependency pass names
    }

    fn owned_columns(&self) -> &'static [&'static str] {
        &["your_column_name"] // Columns to null out automatically on reset
    }

    fn owned_tables(&self) -> &'static [&'static str] {
        &[] // Secondary table rows to delete on reset
    }

    fn custom_reset(&self, conn: &Connection) -> Result<(), String> {
        // Optional custom reset hook
        Ok(())
    }

    fn load_jobs(&self, conn: &Connection) -> Result<Vec<Self::Job>, String> {
        // Spool all pending jobs upfront in a single clean query!
        let mut stmt = conn.prepare(
            "SELECT tp.id, tp.track_id FROM track_passes tp
             WHERE tp.status = ?1 AND tp.pass_name = 'your_pass_name'
             ORDER BY tp.id ASC",
        ).map_err(|e| e.to_string())?;

        let rows = stmt.query_map([pass_status::PENDING], |row| {
            Ok(YourJob {
                pass_id: row.get(0)?,
                track_id: row.get(1)?,
            })
        })

From robertolupi/deep-cuts, AGPL-3.0.

More from robertolupi/deep-cuts