# AGENTS.md - rust-scribe

## Project Overview

rust-scribe is a high-performance video/audio transcriber with timestamps using Rust and Whisper. It extracts audio from video files and transcribes them using the Whisper.cpp library.

## Build Commands

```bash
# Build the project (debug mode)
cargo build

# Build release version
cargo build --release

# Run the application
cargo run --release -- <input_file> --model <model_path> [options]

# Example usage:
cargo run --release -- video.mp4 --model models/ggml-base.bin --language zh
```

### Running Tests

```bash
# Run all tests
cargo test

# Run a single test by name
cargo test <test_name>

# Run tests with output
cargo test -- --nocapture
```

### Linting and Formatting

```bash
# Run clippy for linting
cargo clippy

# Fix clippy suggestions automatically
cargo clippy --fix

# Format code
cargo fmt

# Check formatting
cargo fmt --check
```

## Dependencies

- **ffmpeg-next** (v8.0): FFmpeg bindings for audio extraction and resampling
- **whisper-rs** (v0.12): Rust bindings for Whisper.cpp
- **whisper-rs-sys** (v0.10): Low-level Whisper bindings
- **clap** (v4.5): CLI argument parsing
- **anyhow** (v1.0): Error handling
- **ndarray** (v0.15): Array operations

## Code Style Guidelines

### Formatting
- Use `cargo fmt` for consistent formatting
- 4-space indentation (Rust default)
- Maximum line length: 100 characters (default)

### Imports
- Group imports by crate: std → external → local
- Use absolute paths with `crate::` for internal modules
- Prefer bringing traits into scope when using them

```rust
use std::path::Path;
use anyhow::{Context, Result};
use clap::Parser;
use ffmpeg_next as ffmpeg;
```

### Naming Conventions
- **Variables/functions**: snake_case (e.g., `extract_audio_to_f32`, `audio_data`)
- **Types/Enums**: PascalCase (e.g., `Args`, `WhisperContext`)
- **Constants**: SCREAMING_SNAKE_CASE (e.g., `WHISPER_SAMPLE_RATE`)
- **Files**: snake_case (e.g., `main.rs`)

### Error Handling
- Use `anyhow::Result<T>` for application-level error handling
- Use `?` operator for propagating errors
- Use `Context` trait for adding context to errors
- Use `anyhow::bail!` for early returns with errors
- Provide descriptive error messages in Chinese or English

```rust
fn load_config() -> Result<Config> {
    let file = File::open("config.toml")
        .context("Failed to open config file")?;
    // ...
}
```

### Unsafe Code
- Minimize unsafe code; isolate it in small, well-documented functions
- Use `unsafe` block only when necessary (e.g., FFI callbacks)
- Document preconditions and invariants

```rust
unsafe extern "C" fn progress_callback(...) {
    // Document what this callback does
    // Keep unsafe block minimal
}
```

### Documentation
- Add doc comments (`///`) for public functions
- Document parameters and return values
- Include usage examples for complex functions

### Performance Considerations
- Use `AtomicU64`/`AtomicBool` for global state in callbacks
- Pre-allocate vectors with `Vec::with_capacity()` when size is known
- Use `saturating_*` operations to prevent overflow
- Reuse objects instead of creating new ones in loops

### Type Annotations
- Prefer explicit types for function signatures
- Use type inference for obvious local variables
- Use primitive types (`u32`, `f64`, etc.) over aliases

### Control Flow
- Use early returns to reduce nesting
- Prefer `?` over `match` for simple error propagation
- Use `if let` for optional values when pattern matching is simple

## Project Structure

```
rust-scribe/
├── src/
│   └── main.rs           # Main application code
├── models/               # Whisper model files
├── Cargo.toml           # Project manifest
└── .cargo/
    └── config.toml      # Cargo configuration
```

## Configuration

### CLI Arguments
- `input_file` (positional): Path to video/audio file
- `--model`: Path to Whisper model file
- `--language`: Target language (optional, auto-detects if not specified)
- `--verbose`: Enable verbose output

### Model Requirements
Place Whisper model files (e.g., `ggml-base.bin`) in the `models/` directory.

## Common Tasks

### Adding a New Dependency
Add to `[dependencies]` section in `Cargo.toml`:
```toml
package_name = "version"
```

### Adding a New Feature
1. Implement the feature in a new function in `src/main.rs`
2. Add CLI argument if needed in `Args` struct
3. Test with sample audio/video files

### Debugging
- Use `eprintln!` for debug output (goes to stderr)
- Use `println!` for progress messages
- Enable `--verbose` flag for Whisper debug output