# cadence

High-retention auto-editor for raw video recordings. It transcribes your audio, cuts silences and filler words, and writes a native `.kdenlive` project ready for final polish — plus `.srt` captions and an LLM-friendly transcript.

## Quick start

### Linux

```sh
# uv — installs to ~/.local/bin
curl -LsSf https://astral.sh/uv/install.sh | sh

# FFmpeg — pick your distro
sudo apt install ffmpeg                           # Debian / Ubuntu
sudo dnf swap ffmpeg-free ffmpeg --allowerasing   # Fedora
sudo pacman -S ffmpeg                             # Arch

# Run
uv run cadence.py recording.mp4 --preset balanced --captions
```

> - **uv** installs to `~/.local/bin`; make sure that directory is on your `PATH` (the installer normally adds it — otherwise `export PATH="$HOME/.local/bin:$PATH"` in your shell profile).
> - **Fedora**: enable [RPM Fusion](https://rpmfusion.org/Configuration) first. Fedora ships `ffmpeg-free`, which conflicts with the full `ffmpeg` package, so swap rather than install — `sudo dnf swap ffmpeg-free ffmpeg --allowerasing`.
> - **Nobara**: codecs are managed by Nobara and manual changes are blocked. Run `nobara-sync install-codecs` (or the Codec Wizard) instead of `dnf swap`.

### macOS

```sh
brew install uv ffmpeg

uv run cadence.py recording.mp4 --preset balanced --captions
```

### Windows (PowerShell)

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # uv
winget install -e --id Gyan.FFmpeg                                                   # FFmpeg

uv run cadence.py recording.mp4 --preset balanced --captions
```

## Install as a command (Linux & macOS)

Make `cadence` available everywhere by symlinking the script into a directory on your `PATH`:

```sh
chmod +x cadence.py
mkdir -p ~/.local/bin
ln -sf "$PWD/cadence.py" ~/.local/bin/cadence
```

Now call it from any directory:

```sh
cadence recording.mp4 --preset balanced --captions
```

`~/.local/bin` is added to `PATH` by the uv installer; if it isn't, add `export PATH="$HOME/.local/bin:$PATH"` to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.).

## Output

- `recording.kdenlive` — the edited project.
- `recording.srt` and `recording_llm_transcript.txt` — generated when `--captions` is used.

Presets: `relaxed`, `balanced`, `punchy`. See all options with `uv run cadence.py --help`.

## Development

Run the linter and tests locally:

```sh
uvx ruff check .
uv run --with pytest pytest -q
```

The test suite needs only `pytest` — `cadence.py` imports nothing third-party at module level, so no torch/whisper/ffmpeg is required to run it. CI runs both via Forgejo Actions (`.forgejo/workflows/ci.yml`).