cadence/README.md

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

# 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 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

brew install uv ffmpeg

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

Windows (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:

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

Now call it from any directory:

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:

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).